@ejstembler/pi-classifier-router 1.0.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ejstembler/pi-classifier-router",
+  "version": "1.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/ejstembler/pi-classifier-router.git"
+  },
+  "homepage": "https://gitlab.com/ejstembler/pi-classifier-router#readme",
+  "bugs": {
+    "url": "https://gitlab.com/ejstembler/pi-classifier-router/-/issues"
+  },
+  "description": "Classifier-driven model router for pi and Oh My Pi (omp): routes each prompt to a model using Jev (TypeSafe) or Laya typed decisions, with circuit breaking and fallback chains",
+  "main": "src/index.ts",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "pi-package",
+    "omp-extension",
+    "pi-extension",
+    "jev",
+    "laya",
+    "router"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src",
+    "python",
+    "examples",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@types/node": "^24.13.6",
+    "typescript": "^5.9.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  }
+}

package/python/laya_worker.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""Laya sidecar worker: NDJSON request/response over stdio.
+
+stdout carries exactly one JSON object per line and nothing else, so the
+TypeScript client can parse strictly; every diagnostic (including warnings and
+progress) goes to stderr. Module-level state keeps the checkpoints loaded across
+requests.
+
+Protocol
+    request  {"id": <int>, "op": "predict"|"ping"|"preload"|"shutdown", ...}
+    reply    {"id": <int>, "ok": true,  "result": {...}}
+           | {"id": <int>, "ok": false, "error": "...", "kind": "unavailable"|"timeout"|"protocol"}
+    event    {"event": "ready", "version": "...", "loaded": ["english", ...]}
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import traceback
+
+
+def emit(payload: dict) -> None:
+    """Write one JSON line and flush immediately (the client is line-driven)."""
+    sys.stdout.write(json.dumps(payload) + "\n")
+    sys.stdout.flush()
+
+
+try:
+    import laya
+except Exception as exc:  # A missing or broken install must not look like a protocol fault.
+    emit({"event": "error", "error": f"laya import failed: {exc!r}", "kind": "unavailable"})
+    print("laya_worker: could not import laya", file=sys.stderr)
+    print(traceback.format_exc(), file=sys.stderr)
+    sys.stderr.flush()
+    raise SystemExit(2)
+
+
+STATE = {"agent": None, "loaded": []}
+
+
+def describe_loaded(agent, fallback: str | None) -> list[str]:
+    """Best-effort checkpoint names, for the ready/preload/ping payloads."""
+    for attr in ("loaded", "checkpoints", "loaded_checkpoints", "checkpoint_names"):
+        value = getattr(agent, attr, None)
+        if isinstance(value, dict) and value:
+            return [str(key) for key in value]
+        if isinstance(value, (list, tuple)) and value:
+            return [str(item) for item in value]
+    return [fallback] if fallback else []
+
+
+def ensure_agent(args) -> object:
+    """Load the checkpoints once; later calls reuse the module-level agent."""
+    if STATE["agent"] is not None:
+        return STATE["agent"]
+    if args.router:
+        kwargs: dict = {"preload": args.preload}
+        if args.device:
+            kwargs["device"] = args.device
+        try:
+            agent = laya.Router(max_loaded=args.max_loaded, **kwargs)
+        except TypeError:
+            # Older Router builds do not take max_loaded.
+            agent = laya.Router(**kwargs)
+    else:
+        kwargs = {"subfolder": args.subfolder or None}
+        if args.device:
+            kwargs["device"] = args.device
+        agent = laya.load(args.repo, **kwargs)
+    STATE["agent"] = agent
+    return agent
+
+
+def normalize(reply) -> dict:
+    """Reduce a backend reply to `{model?, answers, usage?}`."""
+    if isinstance(reply, dict):
+        model = reply.get("model")
+        answers = reply.get("answers")
+        usage = reply.get("usage")
+    else:
+        model = getattr(reply, "model", None)
+        answers = getattr(reply, "answers", None)
+        usage = getattr(reply, "usage", None)
+    if not isinstance(answers, dict):
+        raise ValueError("laya returned no answers mapping")
+    result: dict = {"answers": answers}
+    if isinstance(model, str):
+        result["model"] = model
+    if isinstance(usage, dict):
+        result["usage"] = usage
+    return result
+
+
+def error_kind(exc: BaseException) -> str:
+    if isinstance(exc, TimeoutError):
+        return "timeout"
+    if isinstance(exc, (ImportError, RuntimeError)):
+        return "unavailable"
+    return "protocol"
+
+
+def handle(request: dict, args) -> dict | None:
+    """Serve one request; returns the reply, or None for shutdown."""
+    rid = request.get("id")
+    op = request.get("op")
+
+    if op == "predict":
+        agent = ensure_agent(args)
+        state = request.get("state")
+        questions = request.get("questions")
+        model = request.get("model")
+        reply = agent.predict(state, questions, model=model) if model else agent.predict(state, questions)
+        return {"id": rid, "ok": True, "result": normalize(reply)}
+
+    if op == "ping":
+        return {
+            "id": rid,
+            "ok": True,
+            "result": {
+                "laya": True,
+                "version": getattr(laya, "__version__", "unknown"),
+                "loaded": list(STATE["loaded"]),
+            },
+        }
+
+    if op == "preload":
+        agent = ensure_agent(args)
+        STATE["loaded"] = describe_loaded(agent, args.subfolder or "english")
+        return {"id": rid, "ok": True, "result": {"loaded": list(STATE["loaded"])}}
+
+    if op == "shutdown":
+        return {"id": rid, "ok": True, "result": {"bye": True}}
+
+    return {"id": rid, "ok": False, "error": f"unknown op: {op!r}", "kind": "protocol"}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="laya_worker", description="Laya System One sidecar")
+    parser.add_argument("--repo", required=True, help="Hugging Face repo bundling the checkpoints")
+    parser.add_argument("--subfolder", default="", help="checkpoint subfolder; empty means the English root")
+    parser.add_argument("--device", default="", help="torch device; empty means auto-detect")
+    parser.add_argument("--router", action="store_true", help="serve through laya.Router")
+    parser.add_argument("--preload", action="store_true", help="load checkpoints before serving")
+    parser.add_argument("--max-loaded", type=int, default=1, help="checkpoint budget passed to laya.Router")
+    args = parser.parse_args()
+
+    try:
+        sys.stdout.reconfigure(line_buffering=True)
+    except Exception:
+        pass  # flush() after every line is the real guarantee.
+
+    if args.preload:
+        ensure_agent(args)
+        STATE["loaded"] = describe_loaded(STATE["agent"], args.subfolder or "english")
+    else:
+        STATE["loaded"] = []
+
+    emit(
+        {
+            "event": "ready",
+            "version": getattr(laya, "__version__", "unknown"),
+            "loaded": list(STATE["loaded"]),
+        }
+    )
+
+    for raw in sys.stdin:
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+        except Exception as exc:
+            print(f"laya_worker: ignoring unparseable request line ({exc})", file=sys.stderr)
+            continue
+        if not isinstance(request, dict):
+            print("laya_worker: ignoring non-object request", file=sys.stderr)
+            continue
+
+        try:
+            reply = handle(request, args)
+            if reply is not None:
+                emit(reply)
+        except BaseException as exc:
+            print(traceback.format_exc(), file=sys.stderr)
+            emit(
+                {
+                    "id": request.get("id"),
+                    "ok": False,
+                    "error": f"{type(exc).__name__}: {exc}",
+                    "kind": error_kind(exc),
+                }
+            )
+
+        if request.get("op") == "shutdown":
+            sys.stdout.flush()
+            return 0
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/python/requirements.txt

@@ -0,0 +1,10 @@
+# Laya sidecar dependencies for python/laya_worker.py.
+#
+# Upstream floor: Python 3.10+, transformers>=5, torch>=2.14. Install these
+# first (or let pip resolve them transitively below) and match the wheels to
+# the machine:
+#   * CPU-only installs are supported but slower; use the CPU wheel index for
+#     torch and leave --device unset (auto-detect) or set it to "cpu".
+#   * CUDA/MPS installs should use the platform-specific torch wheels before
+#     installing laya.
+laya

package/src/breaker.ts

@@ -0,0 +1,127 @@
+/**
+ * Per-model circuit breaker.
+ *
+ * `closed` -> `open` after `failureThreshold` consecutive failures.
+ * `open` -> `half_open` once `cooldownMs` has elapsed, letting through at most
+ * `halfOpenMaxTrials` concurrent probes. A probe success closes the circuit; a
+ * probe failure re-opens it with a fresh cooldown.
+ *
+ * The clock is injectable so tests need no timers. `allow` is a query: it must
+ * stay safe to call repeatedly (the extension arbitrates availability per
+ * prompt), so it never accumulates failures or successes.
+ */
+
+import type { CircuitBreakerConfig } from "./types.ts";
+
+export type BreakerState = "closed" | "open" | "half_open";
+
+export interface BreakerSnapshot {
+  spec: string;
+  state: BreakerState;
+  failures: number;
+  openedAt: number | null;
+  halfOpenTrials: number;
+}
+
+interface Circuit {
+  state: BreakerState;
+  failures: number;
+  openedAt: number | null;
+  /** Probes started while half-open and not yet resolved by a record call. */
+  halfOpenTrials: number;
+}
+
+export class CircuitBreaker {
+  readonly #config: CircuitBreakerConfig;
+  readonly #now: () => number;
+  readonly #circuits = new Map<string, Circuit>();
+
+  constructor(config: CircuitBreakerConfig, now: () => number = Date.now) {
+    this.#config = config;
+    this.#now = now;
+  }
+
+  #circuit(spec: string): Circuit {
+    const existing = this.#circuits.get(spec);
+    if (existing) return existing;
+    const created: Circuit = { state: "closed", failures: 0, openedAt: null, halfOpenTrials: 0 };
+    this.#circuits.set(spec, created);
+    return created;
+  }
+
+  /** Whether a request to `spec` may proceed right now. */
+  allow(spec: string): boolean {
+    const circuit = this.#circuit(spec);
+
+    if (circuit.state === "closed") return true;
+
+    if (circuit.state === "open") {
+      if (circuit.openedAt === null || this.#now() - circuit.openedAt < this.#config.cooldownMs) return false;
+      circuit.state = "half_open";
+      circuit.halfOpenTrials = 0;
+      circuit.halfOpenTrials += 1;
+      return true;
+    }
+
+    if (circuit.halfOpenTrials >= this.#config.halfOpenMaxTrials) return false;
+    circuit.halfOpenTrials += 1;
+    return true;
+  }
+
+  recordSuccess(spec: string): void {
+    const circuit = this.#circuit(spec);
+    circuit.state = "closed";
+    circuit.failures = 0;
+    circuit.openedAt = null;
+    circuit.halfOpenTrials = 0;
+  }
+
+  recordFailure(spec: string): void {
+    const circuit = this.#circuit(spec);
+
+    if (circuit.state === "half_open") {
+      circuit.state = "open";
+      circuit.openedAt = this.#now();
+      circuit.halfOpenTrials = 0;
+      return;
+    }
+
+    circuit.failures += 1;
+    if (circuit.state === "closed" && circuit.failures >= this.#config.failureThreshold) {
+      circuit.state = "open";
+      circuit.openedAt = this.#now();
+    }
+  }
+
+  /** Clear one spec, or every spec when called without an argument. */
+  reset(spec?: string): void {
+    if (spec === undefined) {
+      this.#circuits.clear();
+      return;
+    }
+    this.#circuits.delete(spec);
+  }
+
+  /** One entry per known spec, in first-seen order. */
+  snapshot(): BreakerSnapshot[] {
+    const snapshots: BreakerSnapshot[] = [];
+    for (const [spec, circuit] of this.#circuits) {
+      snapshots.push({
+        spec,
+        state: circuit.state,
+        failures: circuit.failures,
+        openedAt: circuit.openedAt,
+        halfOpenTrials: circuit.halfOpenTrials,
+      });
+    }
+    return snapshots;
+  }
+
+  /** First candidate currently allowing a request, or null when none do. */
+  firstAvailable(chain: string[]): string | null {
+    for (const spec of chain) {
+      if (this.allow(spec)) return spec;
+    }
+    return null;
+  }
+}

package/src/classify/http.ts

@@ -0,0 +1,176 @@
+/**
+ * Shared System-One HTTP client.
+ *
+ * Both backends speak the same wire format, so this is the single transport:
+ * `POST <endpoint>` with `Authorization: Bearer <token>` (only when a token is
+ * configured and present), `Content-Type: application/json`, and body
+ * `{ state, model?, questions }`; response `{ model?, answers, usage? }`.
+ *
+ * The bearer token is read from the configured environment variable and is
+ * never logged or embedded in errors. Every request is bounded by `timeoutMs`,
+ * composed with the caller's own signal so either side can abort, and the
+ * timer is always cleared.
+ */
+
+import { ClassifierError } from "../types.ts";
+import type {
+  Answers,
+  ClassificationResult,
+  Classifier,
+  ClassifierErrorCode,
+  ClassifierState,
+  ClassifyOptions,
+  Questions,
+} from "../types.ts";
+import type { ClassifierDeps } from "./index.ts";
+
+/** Body snippet length kept for diagnostics; long bodies are never echoed. */
+const SNIPPET_LIMIT = 200;
+
+export interface HttpClassifierOptions {
+  /** Backend id reported on `Classifier.name` and on `ClassifierError.backend`. */
+  name: string;
+  endpoint: string;
+  /** Value for the request body's `model` field; omitted from the body when null. */
+  model: string | null;
+  /** Env var holding the bearer token; when unset or empty, no Authorization header is sent. */
+  apiKeyEnvVar: string;
+  timeoutMs: number;
+}
+
+export function createHttpClassifier(options: HttpClassifierOptions, deps: ClassifierDeps = {}): Classifier {
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const backend = options.name;
+
+  function token(): string {
+    const envVar = options.apiKeyEnvVar;
+    if (envVar.trim() === "") return "";
+    const fromDeps = deps.env?.[envVar];
+    const value = fromDeps ?? process.env[envVar];
+    return (value ?? "").trim();
+  }
+
+  return {
+    name: backend,
+
+    /**
+     * Uniform no-op: probing the endpoint would spend tokens for no signal, and
+     * `classify` works without a prior warmup.
+     */
+    async warmup(): Promise<void> {},
+
+    async classify(
+      state: ClassifierState,
+      questions: Questions,
+      classifyOptions?: ClassifyOptions,
+    ): Promise<ClassificationResult> {
+      const bearer = token();
+      const envVar = options.apiKeyEnvVar;
+      if (bearer === "" && envVar.trim() !== "") {
+        throw new ClassifierError(
+          backend,
+          "unavailable",
+          `${envVar} is not set; ${backend} is unavailable`,
+        );
+      }
+
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (bearer !== "") headers["Authorization"] = `Bearer ${bearer}`;
+
+      const body: Record<string, unknown> = { state, questions };
+      if (options.model !== null) body["model"] = options.model;
+
+      const controller = new AbortController();
+      let timedOut = false;
+      const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+      }, options.timeoutMs);
+      const caller = classifyOptions?.signal;
+      const onCallerAbort = (): void => controller.abort();
+      if (caller) {
+        if (caller.aborted) controller.abort();
+        else caller.addEventListener("abort", onCallerAbort, { once: true });
+      }
+
+      try {
+        const response = await fetchImpl(options.endpoint, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+
+        const bodyText = await response.text();
+        if (!response.ok) {
+          const code: ClassifierErrorCode =
+            response.status === 401 || response.status === 403
+              ? "auth"
+              : response.status === 429 || response.status >= 500
+                ? "unavailable"
+                : "protocol";
+          const collapsed = bodyText.replace(/\s+/g, " ").trim().slice(0, SNIPPET_LIMIT);
+          throw new ClassifierError(
+            backend,
+            code,
+            `${backend} endpoint returned ${response.status}: ${collapsed}`,
+          );
+        }
+
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(bodyText);
+        } catch (error) {
+          throw new ClassifierError(backend, "protocol", `${backend} response was not JSON`, {
+            cause: error,
+          });
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+          throw new ClassifierError(backend, "protocol", `${backend} response was not a JSON object`);
+        }
+
+        const record = parsed as Record<string, unknown>;
+        const answers = record["answers"];
+        if (answers === null || typeof answers !== "object" || Array.isArray(answers)) {
+          throw new ClassifierError(backend, "protocol", `${backend} response has no answers object`);
+        }
+
+        const result: ClassificationResult = { answers: answers as Answers };
+        if (typeof record["model"] === "string") result.model = record["model"];
+        const usage = record["usage"];
+        if (usage !== null && typeof usage === "object" && !Array.isArray(usage)) {
+          result.usage = usage as ClassificationResult["usage"];
+        }
+        return result;
+      } catch (error) {
+        if (error instanceof ClassifierError) throw error;
+        if (controller.signal.aborted) {
+          if (caller?.aborted) {
+            throw new ClassifierError(backend, "aborted", `${backend} request aborted by caller`, {
+              cause: error,
+            });
+          }
+          if (timedOut) {
+            throw new ClassifierError(
+              backend,
+              "timeout",
+              `${backend} request exceeded ${options.timeoutMs}ms`,
+              { cause: error },
+            );
+          }
+        }
+        throw new ClassifierError(
+          backend,
+          "transport",
+          `${backend} request failed: ${error instanceof Error ? error.message : String(error)}`,
+          { cause: error },
+        );
+      } finally {
+        clearTimeout(timer);
+        if (caller) caller.removeEventListener("abort", onCallerAbort);
+      }
+    },
+
+    async dispose(): Promise<void> {},
+  };
+}

package/src/classify/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Classifier selection: one factory per backend, chosen by `config.backend`.
+ */
+
+import type { Classifier, RouterConfig } from "../types.ts";
+import { createJevClassifier } from "./jev.ts";
+import { createLayaClassifier, type ChildProcessLike, type LayaSpawn } from "./laya.ts";
+import { createLayaHttpClassifier } from "./laya-http.ts";
+
+/** Injection seams for tests and for the extension's own environment. */
+export interface ClassifierDeps {
+  /** Environment for token lookup; defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** `fetch` override; defaults to the global implementation. */
+  fetchImpl?: typeof fetch;
+  /** Sidecar spawner; defaults to `node:child_process.spawn`. */
+  spawnImpl?: LayaSpawn;
+  /** Diagnostic sink for non-fatal sidecar noise. */
+  logger?: (message: string) => void;
+  /** Base for relative `laya.workerScript` paths; defaults to the repo root. */
+  extensionRoot?: string;
+}
+
+export function createClassifier(config: RouterConfig, deps: ClassifierDeps = {}): Classifier {
+  if (config.backend === "laya") {
+    return config.laya.transport === "http"
+      ? createLayaHttpClassifier(config.laya, deps)
+      : createLayaClassifier(config.laya, deps);
+  }
+  return createJevClassifier(config.jev, deps);
+}
+
+export type { ChildProcessLike, LayaSpawn };
+export type { LayaTransport } from "../types.ts";

package/src/classify/jev.ts

@@ -0,0 +1,23 @@
+/**
+ * TypeSafe Jev (System One) classifier.
+ *
+ * Jev speaks the shared System-One HTTP wire format, so this is a thin wrapper
+ * over `createHttpClassifier` pinned to the `jev` backend id.
+ */
+
+import type { Classifier, JevBackendConfig } from "../types.ts";
+import { createHttpClassifier } from "./http.ts";
+import type { ClassifierDeps } from "./index.ts";
+
+export function createJevClassifier(config: JevBackendConfig, deps: ClassifierDeps = {}): Classifier {
+  return createHttpClassifier(
+    {
+      name: "jev",
+      endpoint: config.endpoint,
+      model: config.model,
+      apiKeyEnvVar: config.apiKeyEnvVar,
+      timeoutMs: config.timeoutMs,
+    },
+    deps,
+  );
+}

package/src/classify/laya-http.ts

@@ -0,0 +1,28 @@
+/**
+ * Laya (remote System One) classifier over HTTP.
+ *
+ * Targets any host running the same typed-question protocol as the local
+ * sidecar: a containerized `python/laya_worker.py`, a FastAPI wrapper, or any
+ * other compatible System-One server. It spawns no child process, so the
+ * deployment shape "one shared GPU host, thin TypeScript clients" needs no
+ * local Laya install.
+ *
+ * The remote host owns checkpoint selection, so no `model` field is sent.
+ */
+
+import type { Classifier, LayaBackendConfig } from "../types.ts";
+import { createHttpClassifier } from "./http.ts";
+import type { ClassifierDeps } from "./index.ts";
+
+export function createLayaHttpClassifier(config: LayaBackendConfig, deps: ClassifierDeps = {}): Classifier {
+  return createHttpClassifier(
+    {
+      name: "laya",
+      endpoint: config.endpoint,
+      model: null,
+      apiKeyEnvVar: config.apiKeyEnvVar,
+      timeoutMs: config.timeoutMs,
+    },
+    deps,
+  );
+}