pi-typesafe-router 0.1.0

package/src/routing.ts

@@ -0,0 +1,84 @@
+import type {
+  CandidateCheck,
+  Classification,
+  Eligibility,
+  Route,
+  RouterConfig,
+  Target,
+} from "./types.ts";
+
+const virtualProviders = new Set(["auto", "smart-router", "typesafe-router"]);
+
+const positiveFinite = (value: number): boolean => Number.isFinite(value) && value > 0;
+
+/** Deterministic preflight only; preserve configured order, never perform runtime retries. */
+export function candidateChecks(
+  targets: readonly Target[],
+  eligibility: Eligibility,
+): CandidateCheck[] {
+  return targets.map((target) => {
+    const reject = (reason: string): CandidateCheck => ({ target, eligible: false, reason });
+
+    if (virtualProviders.has(target.provider.toLowerCase())) return reject("virtual-provider");
+
+    const model = eligibility.models.find(
+      (item) => item.provider === target.provider && item.id === target.model,
+    );
+
+    if (!model) return reject("unknown-model");
+
+    if (
+      !eligibility.available.some(
+        (item) => item.provider === target.provider && item.id === target.model,
+      )
+    )
+      return reject("unavailable");
+
+    if (
+      eligibility.scope.length &&
+      !eligibility.scope.some(
+        (item) => item.provider === target.provider && item.model === target.model,
+      )
+    )
+      return reject("out-of-scope");
+
+    if (eligibility.hasImages && !model.input.includes("image")) return reject("image-unsupported");
+
+    if (!positiveFinite(model.contextWindow) || !positiveFinite(model.maxTokens))
+      return reject("invalid-model-limits");
+
+    if (
+      (eligibility.inputTokens !== null &&
+        (!Number.isFinite(eligibility.inputTokens) || eligibility.inputTokens < 0)) ||
+      !positiveFinite(eligibility.outputReserveTokens)
+    )
+      return reject("invalid-token-budget");
+    const reserve = Math.min(eligibility.outputReserveTokens, model.maxTokens);
+
+    if (eligibility.inputTokens !== null && eligibility.inputTokens + reserve > model.contextWindow)
+      return reject("context-overflow");
+
+    return { target, eligible: true };
+  });
+}
+
+export function chooseRoute(
+  classification: Classification | undefined,
+  config: RouterConfig,
+): Route {
+  if (!classification) return config.defaultRoute;
+  const { choice, confidence } = classification;
+
+  if (
+    choice === "uncertain" ||
+    confidence === undefined ||
+    !Number.isFinite(confidence) ||
+    confidence < config.minConfidence ||
+    confidence < 0 ||
+    confidence > 1 ||
+    !["quick", "standard", "deep"].includes(choice)
+  )
+    return config.uncertainRoute;
+
+  return choice;
+}

package/src/settings.ts

@@ -0,0 +1,63 @@
+import { mkdir, open, readFile, stat } from "node:fs/promises";
+import { z } from "zod";
+import { dirname } from "node:path";
+import { parseConfig } from "./config.ts";
+import type { RouterConfig } from "./types.ts";
+
+const missingFile = z
+  .instanceof(Error)
+  .refine((error) => z.object({ code: z.literal("ENOENT") }).safeParse(error).success);
+
+export async function loadConfig(path: string): Promise<RouterConfig | undefined> {
+  try {
+    if ((await stat(path)).size > 65_536) throw new Error("Router config exceeds 64 KiB");
+    const text = await readFile(path, "utf8");
+
+    if (Buffer.byteLength(text) > 65_536) throw new Error("Router config exceeds 64 KiB");
+    let value: unknown;
+
+    try {
+      value = JSON.parse(text.replace(/^\uFEFF/, ""));
+    } catch {
+      throw new Error("Router config is not valid JSON");
+    }
+
+    return parseConfig(value);
+  } catch (error) {
+    if (missingFile.safeParse(error).success) return undefined;
+    // Config values and filesystem error messages can contain secrets.
+    throw new Error(
+      "Invalid or unreadable router config. Check JSON, fields, bounds and model mappings.",
+    );
+  }
+}
+
+/** Never overwrite an existing configuration, including a symlink. */
+export async function createConfig(path: string, config: RouterConfig): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  const file = await open(path, "wx", 0o600);
+
+  try {
+    await file.writeFile(`${JSON.stringify(config, null, 2)}\n`);
+  } finally {
+    await file.close();
+  }
+}
+
+/** Bound work whose underlying provider may ignore cancellation. No model setters here. */
+export async function abortable<T>(work: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  signal.throwIfAborted();
+  let remove = () => {};
+
+  const cancelled = new Promise<never>((_, reject) => {
+    const listener = () => reject(signal.reason);
+    signal.addEventListener("abort", listener, { once: true });
+    remove = () => signal.removeEventListener("abort", listener);
+  });
+
+  try {
+    return await Promise.race([work(), cancelled]);
+  } finally {
+    remove();
+  }
+}

package/src/types.ts

@@ -0,0 +1,110 @@
+export const TASK_CLASSES = ["quick", "standard", "deep", "uncertain"] as const;
+
+export type TaskClass = (typeof TASK_CLASSES)[number];
+
+export type Route = Exclude<TaskClass, "uncertain">;
+
+export type Mode = "off" | "shadow" | "auto";
+
+export type CredentialSource =
+  | { source: "env"; variable: string }
+  | { source: "pi"; provider: string };
+
+export type Backend =
+  | { type: "typesafe"; model: string; auth: CredentialSource }
+  | { type: "cloudflare"; model: "typesafe/jev"; accountId: string; auth: CredentialSource }
+  | {
+      type: "vercel";
+      model: "typesafe-ai/jev";
+      auth: CredentialSource;
+      zeroDataRetention: boolean;
+    };
+
+export interface Target {
+  provider: string;
+  model: string;
+}
+
+export interface RouterConfig {
+  version: 1;
+  mode: Mode;
+  allowHeadless: boolean;
+  backend: Backend;
+  timeoutMs: number;
+  generationProbeTimeoutMs: number;
+  minConfidence: number;
+  maxContextChars: number;
+  historyMessages: number;
+  outputReserveTokens: number;
+  routes: Record<Route, Target[]>;
+  defaultRoute: Route;
+  uncertainRoute: Route;
+}
+
+export interface ClassificationState {
+  current_request: string;
+  recent_conversation: Array<{ role: "user" | "assistant"; text: string }>;
+}
+
+export interface Classification {
+  choice: TaskClass;
+  probabilities: Record<TaskClass, number>;
+  confidence?: number;
+  requestedModel: string;
+  returnedModel?: string;
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+export type ClassifierFailureCode =
+  | "credentials"
+  | "timeout"
+  | "cancelled"
+  | "network"
+  | "invalid-response"
+  | "http";
+
+export class ClassifierError extends Error {
+  constructor(
+    public readonly code: ClassifierFailureCode,
+    public readonly status?: number,
+  ) {
+    super(status === undefined ? `Classifier ${code}` : `Classifier ${code} (HTTP ${status})`);
+    this.name = "ClassifierError";
+  }
+}
+
+export interface ClassifyOptions {
+  signal: AbortSignal;
+  apiKey: string;
+}
+
+export type Classify = (
+  backend: Backend,
+  state: ClassificationState,
+  options: ClassifyOptions,
+) => Promise<Classification>;
+
+export interface ModelInfo {
+  provider: string;
+  id: string;
+  input: readonly string[];
+  contextWindow: number;
+  maxTokens: number;
+}
+
+export interface Eligibility {
+  models: readonly ModelInfo[];
+  available: readonly ModelInfo[];
+  scope: readonly Target[];
+  hasImages: boolean;
+  inputTokens: number | null;
+  outputReserveTokens: number;
+}
+
+export interface CandidateCheck {
+  target: Target;
+  eligible: boolean;
+  reason?: string;
+}
+
+export const targetKey = (target: Target): string => `${target.provider}/${target.model}`;

package/src/verification.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import type { RouterContext } from "./host.ts";
+import { targetKey, type RouterConfig, type Target } from "./types.ts";
+
+const providerIdentities = new WeakMap<
+  NonNullable<ReturnType<RouterContext["modelRegistry"]["getProvider"]>>,
+  number
+>();
+
+let nextIdentity = 0;
+
+function providerIdentity(provider: ReturnType<RouterContext["modelRegistry"]["getProvider"]>) {
+  if (!provider) return null;
+  const previous = providerIdentities.get(provider);
+
+  if (previous !== undefined) return previous;
+  const identity = ++nextIdentity;
+  providerIdentities.set(provider, identity);
+
+  return identity;
+}
+
+export function configuredTargets(config: RouterConfig) {
+  const targets = new Map<string, Target>();
+
+  for (const chain of Object.values(config.routes))
+    for (const target of chain) targets.set(targetKey(target), target);
+
+  return [...targets.values()];
+}
+
+/** Hash configuration and resolved registry references; never persist or display credential material. */
+export function verificationFingerprint(
+  config: RouterConfig,
+  registry: RouterContext["modelRegistry"],
+) {
+  const targets = configuredTargets(config);
+  const providerIds = new Set(targets.map((target) => target.provider));
+
+  if (config.backend.auth.source === "pi") providerIds.add(config.backend.auth.provider);
+
+  const providers = [...providerIds].map((provider) => ({
+    provider,
+    // Pi replaces the composed provider when models.json/native registration changes.
+    identity: providerIdentity(registry.getProvider(provider)),
+    authSource: registry.getProviderAuthStatus(provider),
+    extensionConfig: registry.getRegisteredProviderConfig(provider),
+  }));
+
+  const models = targets.map((target) => ({
+    target,
+    model: registry.find(target.provider, target.model),
+  }));
+
+  return createHash("sha256").update(JSON.stringify({ config, providers, models })).digest("hex");
+}
+
+export interface VerifiedGeneration {
+  fingerprint: string;
+  passed: Set<string>;
+  checkedAt: string;
+}