pi-bifrost 0.1.0

package/routing.ts

@@ -0,0 +1,173 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+
+export type RoutingStrategy =
+  | "first"
+  | "cheapest"
+  | "cheapest_input"
+  | "cheapest_output"
+  | "largest_context"
+  | "random"
+  | "fastest";
+
+export interface RouteRule {
+  pattern: string;
+  model: string;
+}
+
+export function modelKey(model: Model<Api> | undefined): string {
+  if (!model) return "none";
+  return `${model.provider}/${model.id}`;
+}
+
+/** Sum of input + output token costs per 1M tokens. Does not include cache read/write costs. */
+export function modelCost(model: Model<Api>): number {
+  return model.cost.input + model.cost.output;
+}
+
+/** Input token cost only. */
+export function modelInputCost(model: Model<Api>): number {
+  return model.cost.input;
+}
+
+/** Output token cost only. */
+export function modelOutputCost(model: Model<Api>): number {
+  return model.cost.output;
+}
+
+/** Context window size. */
+export function modelContextSize(model: Model<Api>): number {
+  return model.contextWindow;
+}
+
+export function findOneModel(
+  ctx: ExtensionContext,
+  pattern: string,
+): Model<Api> | undefined {
+  if (!pattern) return undefined;
+
+  if (pattern.includes("/")) {
+    const [provider, ...idParts] = pattern.split("/");
+    const id = idParts.join("/");
+    return ctx.modelRegistry.find(provider, id);
+  }
+
+  const lower = pattern.toLowerCase();
+  const available = ctx.modelRegistry.getAvailable();
+  return available.find(
+    (m) =>
+      m.id.toLowerCase().includes(lower) ||
+      m.provider.toLowerCase().includes(lower),
+  );
+}
+
+export function findCandidates(
+  ctx: ExtensionContext,
+  pattern: string | string[] | undefined,
+): Model<Api>[] {
+  if (!pattern) return [];
+
+  const candidates: Model<Api>[] = [];
+  const seen = new Set<string>();
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  // Resolve once — avoid N getAvailable() calls for N substring patterns.
+  const available = ctx.modelRegistry.getAvailable();
+
+  for (const p of patterns) {
+    if (p.includes("/")) {
+      const model = findOneModel(ctx, p);
+      if (model) {
+        const key = modelKey(model);
+        if (!seen.has(key)) {
+          seen.add(key);
+          candidates.push(model);
+        }
+      }
+    } else {
+      const lower = p.toLowerCase();
+      for (const m of available) {
+        if (
+          !seen.has(modelKey(m)) &&
+          (m.id.toLowerCase().includes(lower) ||
+            m.provider.toLowerCase().includes(lower))
+        ) {
+          seen.add(modelKey(m));
+          candidates.push(m);
+        }
+      }
+    }
+  }
+
+  return candidates;
+}
+
+export function selectModel(
+  candidates: Model<Api>[],
+  strategy: RoutingStrategy,
+): Model<Api> | undefined {
+  if (candidates.length === 0) return undefined;
+
+  switch (strategy) {
+    case "cheapest":
+      return [...candidates].sort((a, b) => modelCost(a) - modelCost(b))[0];
+    case "cheapest_input":
+      return [...candidates].sort((a, b) => modelInputCost(a) - modelInputCost(b))[0];
+    case "cheapest_output":
+      return [...candidates].sort((a, b) => modelOutputCost(a) - modelOutputCost(b))[0];
+    case "largest_context":
+      return [...candidates].sort((a, b) => modelContextSize(b) - modelContextSize(a))[0];
+    case "random":
+      return candidates[Math.floor(Math.random() * candidates.length)];
+    default:
+      // "first", "fastest" — list order is assumed meaningful.
+      return candidates[0];
+  }
+}
+
+export function resolveModel(
+  ctx: ExtensionContext,
+  pattern: string | string[] | undefined,
+  strategy: RoutingStrategy,
+): Model<Api> | undefined {
+  return selectModel(findCandidates(ctx, pattern), strategy);
+}
+
+export function getStrategy(
+  categoryStrategies: Record<string, RoutingStrategy> | undefined,
+  fallbackStrategy: RoutingStrategy | undefined,
+  category: string,
+): RoutingStrategy {
+  return categoryStrategies?.[category] ?? fallbackStrategy ?? "first";
+}
+
+export function classify(text: string, rules: readonly RouteRule[]): string | undefined {
+  for (const rule of rules) {
+    try {
+      const re = new RegExp(rule.pattern, "i");
+      if (re.test(text)) return rule.model;
+    } catch (err) {
+      console.error(`[bifrost] invalid regex "${rule.pattern}": ${err}`);
+    }
+  }
+  return undefined;
+}
+
+// ── Tier heuristics ───────────────────────────────────────────
+
+/**
+ * Cost thresholds for tier assignment during `/bifrost init`.
+ * Models with cost above FRONTIER are suggested as frontier;
+ * below ECONOMICAL as economical. Everything else is uncategorized
+ * and the user assigns manually. No name-based guessing — naming
+ * conventions change; cost is the stable signal.
+ */
+const FRONTIER_COST_THRESHOLD = 5; // $/1M tokens (input + output)
+const ECONOMICAL_COST_THRESHOLD = 1;
+
+/** Assign a model to a tier based solely on token cost. */
+export function guessTier(model: Model<Api>): "frontier" | "economical" | undefined {
+  const cost = (model.cost?.input ?? 0) + (model.cost?.output ?? 0);
+  if (cost > FRONTIER_COST_THRESHOLD) return "frontier";
+  if (cost < ECONOMICAL_COST_THRESHOLD) return "economical";
+  return undefined;
+}

package/schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://pi.dev/schemas/bifrost.json",
+  "title": "Bifrost Model Router Config",
+  "description": "Configuration for the pi-bifrost query-aware model router. Maps user prompts to model tiers via regex rules and an optional LLM classifier. Merged from extension defaults → global → project-local → root.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Enable or disable the model router. When disabled, all requests use the default model.",
+      "default": true
+    },
+    "default": {
+      "type": "string",
+      "description": "Model tier to use when no rule matches and the classifier returns no category. Must match a key in 'models'.",
+      "default": "economical",
+      "examples": ["economical", "frontier"]
+    },
+    "strategy": {
+      "type": "string",
+      "enum": ["first", "cheapest", "cheapest_input", "cheapest_output", "largest_context", "random", "fastest"],
+      "description": "Model selection strategy. 'first'/'fastest' picks first candidate (list should be pre-sorted). 'cheapest' sorts by input+output cost. 'cheapest_input' by input cost. 'cheapest_output' by output cost. 'largest_context' by context window. 'random' picks randomly.",
+      "default": "first"
+    },
+    "categoryStrategies": {
+      "type": "object",
+      "description": "Per-tier strategy overrides. Keys must match tier names in 'models'. If a tier is not listed here, 'strategy' is used.",
+      "default": { "economical": "cheapest" },
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["first", "cheapest", "cheapest_input", "cheapest_output", "largest_context", "random", "fastest"]
+      }
+    },
+    "models": {
+      "type": "object",
+      "description": "Model tiers. Each key is a tier name (e.g. 'frontier', 'economical'). Values are provider/model patterns — either a single string or an ordered array of candidate patterns.",
+      "default": {},
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        ]
+      },
+      "examples": [
+        {
+          "frontier": ["opencode/deepseek-v4-flash-free"],
+          "economical": ["ollama/qwen2.5-coder:latest", "lmstudio/openai/gpt-oss-20b"]
+        }
+      ]
+    },
+    "rules": {
+      "type": "array",
+      "description": "Regex-based routing rules applied in order. First matching rule determines the model tier. Case-insensitive matching. If no rule matches, the 'default' tier is used. Prefer using bifrost-routes.json for project-specific rules — it overrides this field.",
+      "x-aiHints": {
+        "danger": "Wrong regex can misroute all requests. Test with /bifrost preview <prompt> before committing.",
+        "atomic": true
+      },
+      "items": {
+        "$ref": "#/definitions/RouteRule"
+      }
+    },
+    "classifier": {
+      "$ref": "#/definitions/ClassifierConfig"
+    },
+    "cache": {
+      "$ref": "#/definitions/CacheConfig"
+    },
+    "debug": {
+      "$ref": "#/definitions/DebugConfig"
+    }
+  },
+  "definitions": {
+    "RouteRule": {
+      "type": "object",
+      "required": ["pattern", "model"],
+      "additionalProperties": false,
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "JavaScript regex pattern (without flags, double-escaped). Matched case-insensitively against the user's prompt. Example: '\\\\b(debug|fix|refactor)\\\\b'"
+        },
+        "model": {
+          "type": "string",
+          "description": "Model tier name. Must match a key in the 'models' map."
+        }
+      }
+    },
+    "ClassifierConfig": {
+      "type": "object",
+      "description": "LLM-based classifier that inspects user prompts and selects a tier before falling back to regex rules. Set 'enabled: false' to use regex-only routing.",
+      "required": ["model"],
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable the LLM classifier. When disabled, only regex rules are used.",
+          "default": true
+        },
+        "model": {
+          "type": "string",
+          "description": "Model pattern for the classifier. Use the cheapest model you trust — each classification costs tokens. Example: 'ollama/qwen2.5-coder:latest'"
+        },
+        "endpoint": {
+          "type": "string",
+          "description": "Optional base URL for the classifier when the model is not in pi's model registry. Example: 'http://127.0.0.1:1234/v1'. When set, only method='direct' works for that endpoint."
+        },
+        "method": {
+          "type": "string",
+          "enum": ["direct", "subprocess", "auto"],
+          "description": "How to invoke the classifier. 'direct' uses a fast OpenAI-compatible HTTP call (needs compatible API). 'subprocess' spawns a fresh pi CLI (slower but supports any provider). 'auto' tries direct first, falls back to subprocess.",
+          "default": "auto"
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "description": "Max output tokens for the classifier. Keep it low — only need the category name back.",
+          "default": 20
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2,
+          "description": "Temperature for classifier sampling. 0 for deterministic category selection.",
+          "default": 0
+        },
+        "fallbackToRegex": {
+          "type": "boolean",
+          "description": "Fall back to regex rules when the classifier fails or returns an unknown category.",
+          "default": true
+        },
+        "systemPrompt": {
+          "type": "string",
+          "description": "Custom system prompt for the classifier. Override to change how categories are presented to the LLM.",
+          "default": "You are a routing classifier. Pick the category that best matches the task complexity and type. Respond with only the exact category name. No explanation, no punctuation."
+        }
+      }
+    },
+    "CacheConfig": {
+      "type": "object",
+      "description": "Fuzzy classification cache. Repeated or similar prompts reuse the cached category instead of calling the classifier again.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable the classification cache.",
+          "default": true
+        },
+        "maxEntries": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000,
+          "description": "Maximum number of cached entries. Oldest entries (by last use) are evicted first.",
+          "default": 500
+        },
+        "threshold": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Jaccard similarity threshold for fuzzy cache matches. 0 = any prompt matches. 1 = only exact token matches.",
+          "default": 0.85
+        },
+        "path": {
+          "type": "string",
+          "description": "Custom path for the cache file. Absolute, ~-prefixed, or relative to project root. Default: .pi/bifrost-cache.jsonl"
+        }
+      }
+    },
+    "DebugConfig": {
+      "type": "object",
+      "description": "Structured debug logging. Appends JSONL lines to a file for performance analysis and troubleshooting. Disabled by default.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable debug logging.",
+          "default": false
+        },
+        "path": {
+          "type": "string",
+          "description": "Custom path for the debug log file. Default: .pi/bifrost-debug.jsonl"
+        }
+      }
+    }
+  }
+}

package/tests/cache.test.ts

@@ -0,0 +1,148 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  normalize,
+  lookupCache,
+  touchCacheEntry,
+  findCachedCategory,
+  updateCache,
+  cachePath,
+} from "../cache.ts";
+
+describe("cache", () => {
+  describe("normalize", () => {
+    it("lowercases, strips punctuation, sorts tokens", () => {
+      assert.equal(normalize("Hello, World!"), "hello world");
+      assert.equal(normalize("  Plan   the architecture? "), "architecture plan the");
+    });
+
+    it("returns empty string for empty input", () => {
+      assert.equal(normalize(""), "");
+    });
+
+    it("preserves non-Latin characters", () => {
+      const result = normalize("调试 内存泄漏");
+      assert.ok(result.includes("调试"));
+      assert.ok(result.includes("内存泄漏"));
+    });
+
+    it("normalizes empty string for Jaccard edge case", () => {
+      // Empty-vs-empty should still produce cache-viable normalized form
+      assert.equal(normalize("!@#$%"), "");
+    });
+  });
+
+  describe("lookupCache", () => {
+    it("returns entry for exact match (no mutation)", () => {
+      const entries = [
+        { normalized: "hello world", category: "economical", lastUsed: 1, hits: 5 },
+      ];
+      const result = lookupCache(entries, "Hello World!", 0.85);
+      assert.ok(result);
+      assert.equal(result!.category, "economical");
+      assert.equal(entries[0].hits, 5);
+      assert.equal(entries[0].lastUsed, 1);
+    });
+
+    it("returns entry for fuzzy match above threshold", () => {
+      const entries = [
+        { normalized: "hello world today is nice", category: "economical", lastUsed: 1, hits: 0 },
+      ];
+      const result = lookupCache(entries, "hello world today is good", 0.5);
+      assert.ok(result);
+      assert.equal(result!.category, "economical");
+      assert.equal(entries[0].lastUsed, 1);
+    });
+
+    it("returns undefined when nothing matches", () => {
+      const entries = [
+        { normalized: "hello world", category: "economical", lastUsed: 1, hits: 0 },
+      ];
+      assert.equal(lookupCache(entries, "plan architecture", 0.85), undefined);
+    });
+  });
+
+  describe("touchCacheEntry", () => {
+    it("mutates lastUsed and hits", () => {
+      const entry = { normalized: "hello", category: "economical", lastUsed: 100, hits: 3 };
+      touchCacheEntry(entry);
+      assert.ok(entry.lastUsed > 100);
+      assert.equal(entry.hits, 4);
+    });
+  });
+
+  describe("findCachedCategory", () => {
+    it("returns exact match", () => {
+      const entries = [
+        { normalized: "hello world", category: "economical", lastUsed: 1, hits: 0 },
+      ];
+      assert.equal(findCachedCategory(entries, "Hello World!", 0.85), "economical");
+    });
+
+    it("returns fuzzy match above threshold", () => {
+      const entries = [
+        { normalized: "hello world today is nice", category: "economical", lastUsed: 1, hits: 0 },
+      ];
+      assert.equal(
+        findCachedCategory(entries, "hello world today is good", 0.5),
+        "economical",
+      );
+    });
+
+    it("returns undefined when nothing matches", () => {
+      const entries = [
+        { normalized: "hello world", category: "economical", lastUsed: 1, hits: 0 },
+      ];
+      assert.equal(findCachedCategory(entries, "plan architecture", 0.85), undefined);
+    });
+
+    it("updates hits and lastUsed on match", () => {
+      const entries = [
+        { normalized: "hello", category: "economical", lastUsed: 1, hits: 1 },
+      ];
+      findCachedCategory(entries, "hello", 0.85);
+      assert.equal(entries[0].hits, 2);
+      assert.ok(entries[0].lastUsed > 1);
+    });
+  });
+
+  describe("updateCache", () => {
+    it("adds new entry", () => {
+      const entries = updateCache([], "hello", "economical", 10);
+      assert.equal(entries.length, 1);
+      assert.equal(entries[0].normalized, "hello");
+      assert.equal(entries[0].category, "economical");
+    });
+
+    it("updates existing entry", () => {
+      let entries = updateCache([], "hello", "economical", 10);
+      entries = updateCache(entries, "hello", "frontier", 10);
+      assert.equal(entries.length, 1);
+      assert.equal(entries[0].category, "frontier");
+    });
+
+    it("evicts oldest entries over cap", () => {
+      let entries: ReturnType<typeof updateCache> = [];
+      for (let i = 0; i < 5; i++) {
+        entries = updateCache(entries, `token${i}`, "economical", 3);
+      }
+      assert.equal(entries.length, 3);
+      assert.ok(!entries.some((e) => e.normalized === "token0"));
+    });
+  });
+
+  describe("cachePath", () => {
+    it("defaults to .pi/bifrost-cache.jsonl under cwd", () => {
+      assert.equal(cachePath("/project"), "/project/.pi/bifrost-cache.jsonl");
+    });
+
+    it("expands leading tilde", () => {
+      process.env.HOME = "/home/user";
+      assert.equal(cachePath("/project", "~/cache.jsonl"), "/home/user/cache.jsonl");
+    });
+
+    it("joins relative path to cwd", () => {
+      assert.equal(cachePath("/project", "cache.jsonl"), "/project/cache.jsonl");
+    });
+  });
+});

package/tests/classifier.test.ts

@@ -0,0 +1,48 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  categoryLabel,
+  classificationPrompt,
+  extractCategory,
+} from "../classifier.ts";
+
+describe("classifier", () => {
+  describe("categoryLabel", () => {
+    it("returns category name unchanged", () => {
+      assert.equal(categoryLabel("frontier"), "frontier");
+      assert.equal(categoryLabel("economical"), "economical");
+      assert.equal(categoryLabel("local"), "local");
+    });
+  });
+
+  describe("classificationPrompt", () => {
+    it("lists categories by name", () => {
+      const prompt = classificationPrompt(["frontier", "economical"], "hello");
+      assert.ok(prompt.includes("frontier, economical"));
+      assert.ok(prompt.includes("Request: hello"));
+    });
+  });
+
+  describe("extractCategory", () => {
+    it("extracts exact category name", () => {
+      assert.equal(extractCategory("frontier", ["frontier", "economical"]), "frontier");
+    });
+
+    it("is case-insensitive", () => {
+      assert.equal(extractCategory("Frontier", ["frontier", "economical"]), "frontier");
+    });
+
+    it("handles surrounding whitespace", () => {
+      assert.equal(extractCategory("  economical  ", ["frontier", "economical"]), "economical");
+    });
+
+    it("returns undefined for non-matching text", () => {
+      assert.equal(extractCategory("unknown", ["frontier", "economical"]), undefined);
+    });
+
+    it("does not substring match", () => {
+      // "not economical" should not match "economical"
+      assert.equal(extractCategory("not economical", ["frontier", "economical"]), undefined);
+    });
+  });
+});

package/tests/commands.test.ts

@@ -0,0 +1,116 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+// resolveTierDisplay is not exported from commands.ts — it's internal.
+// The handlers (handleInit, handleBenchmark, handlePreview) are also internal.
+// These are tested via integration tests.
+// This file verifies the routing helpers that commands.ts depends on.
+
+import {
+  getStrategy,
+  selectModel,
+  findCandidates,
+  modelKey,
+  guessTier,
+} from "../routing.ts";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+function makeModel(
+  provider: string,
+  id: string,
+  inputCost = 0,
+  outputCost = 0,
+): Model<Api> {
+  return {
+    provider,
+    id,
+    name: id,
+    api: "openai-completions" as Api,
+    baseUrl: "http://localhost:1234/v1",
+    reasoning: false,
+    input: ["text"],
+    cost: { input: inputCost, output: outputCost, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: 128000,
+    maxTokens: 4096,
+  } as unknown as Model<Api>;
+}
+
+function makeCtx(models: Model<Api>[]): ExtensionContext {
+  return {
+    modelRegistry: {
+      find: (provider: string, id: string) =>
+        models.find((m) => m.provider === provider && m.id === id),
+      getAvailable: () => models,
+    },
+  } as unknown as ExtensionContext;
+}
+
+describe("commands helpers", () => {
+  describe("guessTier", () => {
+    it("classifies expensive models as frontier", () => {
+      const m = makeModel("any", "any-model", 10, 5);
+      assert.equal(guessTier(m), "frontier");
+    });
+
+    it("classifies cheap models as economical", () => {
+      const m = makeModel("any", "any-model", 0.5, 0.2);
+      assert.equal(guessTier(m), "economical");
+    });
+
+    it("classifies free models (cost 0) as economical", () => {
+      const m = makeModel("ollama", "local-model", 0, 0);
+      assert.equal(guessTier(m), "economical");
+    });
+
+    it("returns undefined for middling cost", () => {
+      const m = makeModel("any", "mid-model", 3, 0);
+      assert.equal(guessTier(m), undefined);
+    });
+
+    it("handles missing cost fields gracefully", () => {
+      const m = makeModel("any", "no-cost", 0, 0);
+      (m as any).cost = undefined;
+      assert.equal(guessTier(m), "economical");
+    });
+
+    it("classifies high-cost models (>5) as frontier", () => {
+      const m = makeModel("any", "expensive", 10, 0);
+      assert.equal(guessTier(m), "frontier");
+    });
+  });
+
+  describe("selectModel with cheapest strategy", () => {
+    it("picks lowest input+output cost", () => {
+      const a = makeModel("a", "a", 5, 0);
+      const b = makeModel("b", "b", 1, 0);
+      const c = makeModel("c", "c", 3, 2);
+      const selected = selectModel([a, b, c], "cheapest");
+      assert.equal(modelKey(selected), "b/b");
+    });
+  });
+
+  describe("findCandidates with multiple patterns", () => {
+    it("deduplicates across exact and substring matches", () => {
+      const ctx = makeCtx([
+        makeModel("anthropic", "claude-opus"),
+        makeModel("anthropic", "claude-sonnet"),
+      ]);
+      const result = findCandidates(ctx, ["anthropic/claude-opus", "anthropic"]);
+      assert.equal(result.length, 2);
+    });
+
+    it("returns empty for empty patterns", () => {
+      const ctx = makeCtx([]);
+      assert.equal(findCandidates(ctx, []).length, 0);
+    });
+  });
+
+  describe("getStrategy", () => {
+    it("falls back through category → global → default", () => {
+      assert.equal(getStrategy({ frontier: "cheapest" }, "first", "frontier"), "cheapest");
+      assert.equal(getStrategy({}, "first", "economical"), "first");
+      assert.equal(getStrategy(undefined, undefined, "economical"), "first");
+    });
+  });
+});