Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat: revision pinning + opt-in SHA-256 verification for checkpoint loads (draft for #332)
Aashish59acf353b7a3
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.tsindex 246ff0f6..264ca9af 100644--- a/laya-ts/src/agent.ts+++ b/laya-ts/src/agent.ts@@ -91,6 +91,8 @@ export interface AgentOptions {provider: SessionProvider;tok?: TokenizerLike;cfg?: AgentCfg;+ /** Commit SHA the artifacts were loaded from (pinned/requested or `x-repo-commit`); null for local dirs. */+ revision?: string | null;max_len?: number;head_max_len?: number;temperature?: unknown;@@ -259,6 +261,7 @@ export class Agent extends HookRegistry {hooksRaise: boolean;cfg: AgentCfg;provider: SessionProvider;+ revision: string | null;tok: TokenizerLike;maxLen: number;headMaxLen: number;@@ -275,6 +278,7 @@ export class Agent extends HookRegistry {super();if (!opts || !opts.provider) throw new Error("Agent needs a provider");this.provider = opts.provider;+ this.revision = opts.revision ?? null;// Hooks are opt-in; an unset hook list is a no-op. See hooks.ts.this.hooks = normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd);this.hooksRaise = opts.hooksRaise ?? true;@@ -545,6 +549,13 @@ export class Agent extends HookRegistry {numThreads?: number;/** Per-language temperature overrides; see AgentOptions.lang_temperatures. */lang_temperatures?: AgentOptions["lang_temperatures"];+ /** Commit SHA/branch/tag to fetch; published checkpoints pin to a reviewed SHA by default. */+ revision?: string | null;+ /**+ * Opt-in `{artifact name: SHA-256 hexdigest}` check before any artifact is parsed+ * or executed. A missing artifact or digest mismatch throws and loading is refused.+ */+ expectedSha256?: Record<string, string>;},): Promise<Agent> {const sub = opts?.subfolder ?? null;@@ -553,24 +564,36 @@ export class Agent extends HookRegistry {let cfg: AgentCfg = {};let tokenizerJson: unknown | null = null;let dir = opts?.localDir ?? modelDirOrRepo;+ let revision: string | null = null;let provider: SessionProvider;if (isBrowser) {const { loadWebBundle, createWebProvider } = await import("./providers.js");- const bundle = await loadWebBundle(modelDirOrRepo, { subfolder: sub });+ const bundle = await loadWebBundle(modelDirOrRepo, {+ subfolder: sub,+ revision: opts?.revision,+ expectedSha256: opts?.expectedSha256,+ });cfg = bundle.cfg;tokenizerJson = bundle.tokenizerJson;dir = bundle.dir;- provider = await createWebProvider(dir, { numThreads: opts?.numThreads });+ revision = bundle.revision;+ provider = await createWebProvider(dir, {+ numThreads: opts?.numThreads,+ expectedSha256: opts?.expectedSha256,+ });} else {const { loadNodeBundle, createNodeProvider } = await import("./providers.js");const bundle = await loadNodeBundle(modelDirOrRepo, {subfolder: sub,localDir: opts?.localDir,token: opts?.token,+ revision: opts?.revision,+ expectedSha256: opts?.expectedSha256,});cfg = bundle.cfg;tokenizerJson = bundle.tokenizerJson;dir = bundle.dir;+ revision = bundle.revision;provider = await createNodeProvider(dir, { device: opts?.device, numThreads: opts?.numThreads });}if (!tokenizerJson) {@@ -588,6 +611,6 @@ export class Agent extends HookRegistry {`Incompatible model: tokenizer.json is missing or invalid in ${JSON.stringify(dir)}: ${String(error)}`,);}- return new Agent({ provider, tok, cfg, lang_temperatures: opts?.lang_temperatures });+ return new Agent({ provider, tok, cfg, revision, lang_temperatures: opts?.lang_temperatures });}}diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.tsindex 80bd718e..38e105a3 100644--- a/laya-ts/src/index.ts+++ b/laya-ts/src/index.ts@@ -13,7 +13,7 @@ export type {AgentOptions,PredictOptions,} from "./agent.js";-export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle } from "./providers.js";+export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle, PINNED_REVISIONS, resolveRevision } from "./providers.js";export type { Batch, SessionProvider, ProviderOptions, NodeBundle, WebBundle } from "./providers.js";export { Router, normaliseName, DEFAULT_MODELS } from "./router.js";export type { RoutedResult, RouteDecision, ModelName, ModelSpec } from "./router.js";diff --git a/laya-ts/src/providers.ts b/laya-ts/src/providers.tsindex 01670908..5d6916a1 100644--- a/laya-ts/src/providers.ts+++ b/laya-ts/src/providers.ts@@ -1,6 +1,57 @@/** ONNX session shim: Node (onnxruntime-node) + browser (onnxruntime-web).* Lazy imports only — unit tests with a fake provider never touch onnxruntime. */+/** Reviewed commit SHAs of the published checkpoints (mirror of laya/revisions.py).+ * Loads of these repos pin to the reviewed revision instead of mutable `main`; bump a+ * pin only after the new revision has been reviewed. */+export const PINNED_REVISIONS: Record<string, string> = {+ "convaiinnovations/laya": "55cf4c4ebb4ebe31b2550e8bdf3bd21b99753851",+ "convaiinnovations/laya-multilingual": "e4e9ddf21a7b1903b7acffd8814ad4307bf63a67",+ "convaiinnovations/laya-typed-decisions": "1a793eb568e6718f15941d08f85432581df534e3",+};++/** Explicit `revision` wins; published repos fall back to their reviewed pin; anything+ * else keeps the hub default (`main`). */+export function resolveRevision(repoOrId: string, revision?: string | null): string | null {+ if (revision) return revision;+ return PINNED_REVISIONS[repoOrId] ?? null;+}++/** SHA-256 hex via Web Crypto (browsers and modern Node expose globalThis.crypto). */+async function sha256Hex(data: ArrayBuffer | Uint8Array): Promise<string> {+ const subtle = (globalThis as { crypto?: { subtle?: any } }).crypto?.subtle;+ if (!subtle) {+ throw new Error("laya-ts: SHA-256 verification requires Web Crypto (globalThis.crypto.subtle)");+ }+ const digest = await subtle.digest("SHA-256", data);+ return Array.from(new Uint8Array(digest as ArrayBuffer), (b) => b.toString(16).padStart(2, "0")).join("");+}++/** Reject absolute or escaping digest paths before they ever reach the filesystem. */+function normaliseDigestPath(rel: string): string {+ const norm = String(rel).replace(/\\/g, "/").replace(/^\/+/, "");+ if (!norm || norm === ".." || norm.startsWith("../") || norm.includes("/../")) {+ throw new Error(`laya-ts: unsafe path in expectedSha256: ${JSON.stringify(rel)}`);+ }+ return norm;+}++/** Verify `data` against expectedSha256[rel]; artifacts not listed are left unchecked. */+async function expectDigest(+ rel: string,+ data: ArrayBuffer | Uint8Array,+ expected: Record<string, string>,+): Promise<void> {+ const want = expected[rel] ?? expected[normaliseDigestPath(rel)];+ if (want === undefined) return;+ const got = await sha256Hex(data);+ if (got.toLowerCase() !== String(want).trim().toLowerCase()) {+ throw new Error(+ `laya-ts: SHA-256 mismatch for ${rel}: expected ${want}, got ${got}. Refusing to load the artifact.`,+ );+ }+}+export interface Batch {inputIds: number[][];attentionMask: number[][];@@ -83,6 +134,8 @@ function pickOutput(out: Record<string, any>, names: string[]): any {export interface ProviderOptions {device?: string;numThreads?: number;+ /** Opt-in {artifact name: SHA-256 hexdigest} check for fetched ONNX files (web). */+ expectedSha256?: Record<string, string>;}function applyNumThreads(ort: any, numThreads?: number): void {@@ -159,31 +212,39 @@ async function fetchArrayBuffer(url: string): Promise<ArrayBuffer> {return await res.arrayBuffer();}-async function fetchJson(url: string): Promise<unknown> {- const buf = await fetchArrayBuffer(url);- return JSON.parse(new TextDecoder().decode(buf));-}-export interface NodeBundle {dir: string;cfg: any;tokenizerJson: unknown | null;+ /** Commit SHA the artifacts came from (pinned/requested, or the hub's `x-repo-commit`); null for local dirs. */+ revision: string | null;}export async function loadNodeBundle(modelDirOrRepo: string,- opts?: { subfolder?: string | null; localDir?: string; token?: string | null },+ opts?: {+ subfolder?: string | null;+ localDir?: string;+ token?: string | null;+ revision?: string | null;+ expectedSha256?: Record<string, string>;+ },): Promise<NodeBundle> {const fs: typeof import("node:fs/promises") = await import("node:fs/promises");const path: typeof import("node:path") = await import("node:path");const os: typeof import("node:os") = await import("node:os");const sub = opts?.subfolder ?? null;let dir = opts?.localDir ?? modelDirOrRepo;+ let resolvedRevision: string | null = null;try {const st = await fs.stat(sub ? path.join(dir, sub) : dir);if (st.isDirectory()) dir = sub ? path.join(dir, sub) : dir;else dir = path.dirname(dir);} catch {+ // Pin published repos to their reviewed commit SHA instead of mutable `main`; the+ // revision joins the cache key so differently-pinned artifacts never collide.+ const revision = resolveRevision(modelDirOrRepo, opts?.revision);+ resolvedRevision = revision;const cache = path.join(os.homedir(),".cache",@@ -191,6 +252,7 @@ export async function loadNodeBundle("hf",modelDirOrRepo.replace(/\//g, "__"),sub ?? "root",+ ...(revision && revision !== "main" ? [revision] : []),);await fs.mkdir(cache, { recursive: true });const token =@@ -199,8 +261,10 @@ export async function loadNodeBundle(try {await fs.stat(path.join(cache, f));} catch {- const url = `https://huggingface.co/${modelDirOrRepo}/resolve/main/${sub ? sub + "/" : ""}${f}`;+ const url = `https://huggingface.co/${modelDirOrRepo}/resolve/${revision ?? "main"}/${sub ? sub + "/" : ""}${f}`;const res = await fetch(url, token ? { headers: { Authorization: `Bearer ${token}` } } : undefined);+ const commit = res.headers?.get?.("x-repo-commit");+ if (commit) resolvedRevision = commit;if (!res.ok) {if (f === "rl_agent_config.json") {throw new Error(@@ -211,11 +275,35 @@ export async function loadNodeBundle(}const target = path.join(cache, f);await fs.mkdir(path.dirname(target), { recursive: true });- await fs.writeFile(target, new Uint8Array(await res.arrayBuffer()));+ // Write-then-rename so an interrupted download never leaves a truncated+ // artifact that later loads treat as complete.+ const tmp = `${target}.tmp-${typeof process !== "undefined" ? process.pid : 0}`;+ await fs.writeFile(tmp, new Uint8Array(await res.arrayBuffer()));+ await fs.rename(tmp, target);}}dir = cache;}+ // Opt-in integrity check over the resolved directory (covers local dirs, warm cache,+ // and fresh downloads alike) before any artifact is parsed or executed.+ if (opts?.expectedSha256) {+ const { createHash } = await import("node:crypto");+ for (const [rel, want] of Object.entries(opts.expectedSha256)) {+ const norm = normaliseDigestPath(rel);+ let buf: Uint8Array;+ try {+ buf = new Uint8Array(await fs.readFile(path.join(dir, norm)));+ } catch {+ throw new Error(`laya-ts: cannot verify ${JSON.stringify(rel)}: not found under ${dir}`);+ }+ const got = createHash("sha256").update(buf).digest("hex");+ if (got.toLowerCase() !== String(want).trim().toLowerCase()) {+ throw new Error(+ `laya-ts: SHA-256 mismatch for ${rel}: expected ${want}, got ${got}. Refusing to load the artifact.`,+ );+ }+ }+ }let cfg: any = {};try {cfg = JSON.parse(await fs.readFile(path.join(dir, "rl_agent_config.json"), "utf8"));@@ -233,44 +321,58 @@ export async function loadNodeBundle(// Try the next supported Hugging Face layout.}}- return { dir, cfg, tokenizerJson };+ return { dir, cfg, tokenizerJson, revision: resolvedRevision };}export interface WebBundle {dir: string;cfg: any;tokenizerJson: unknown | null;+ /** Pinned/requested commit SHA, if any (full-URL sources have no implicit revision). */+ revision: string | null;}-function baseUrlFor(repoOrUrl: string, subfolder?: string | null): string {+function baseUrlFor(repoOrUrl: string, subfolder?: string | null, revision?: string | null): string {const sub = subfolder ? `/${subfolder.replace(/^\/+|\/+$/g, "")}` : "";if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(repoOrUrl)) {return `${repoOrUrl.replace(/\/+$/, "")}${sub}`;}- return `https://huggingface.co/${repoOrUrl}/resolve/main${sub}`;+ return `https://huggingface.co/${repoOrUrl}/resolve/${revision ?? "main"}${sub}`;}export async function loadWebBundle(repoOrUrl: string,- opts?: { subfolder?: string | null },+ opts?: {+ subfolder?: string | null;+ revision?: string | null;+ expectedSha256?: Record<string, string>;+ },): Promise<WebBundle> {- const base = baseUrlFor(repoOrUrl, opts?.subfolder ?? null);+ const revision = resolveRevision(repoOrUrl, opts?.revision);+ const base = baseUrlFor(repoOrUrl, opts?.subfolder ?? null, revision);+ const fetchVerifiedJson = async (rel: string): Promise<unknown> => {+ const buf = await fetchArrayBuffer(`${base}/${rel}`);+ if (opts?.expectedSha256) await expectDigest(rel, buf, opts.expectedSha256);+ return JSON.parse(new TextDecoder().decode(buf));+ };let cfg: any;try {- cfg = await fetchJson(`${base}/rl_agent_config.json`);- } catch {+ cfg = await fetchVerifiedJson("rl_agent_config.json");+ } catch (e) {+ if (e instanceof Error && e.message.startsWith("laya-ts: SHA-256 mismatch")) throw e;throw new Error(`Incompatible model: ${JSON.stringify(repoOrUrl)} does not contain 'rl_agent_config.json'.`);}let tokenizerJson: unknown | null = null;for (const candidate of ["tokenizer.json", "tokenizer/tokenizer.json"]) {try {- tokenizerJson = await fetchJson(`${base}/${candidate}`);+ tokenizerJson = await fetchVerifiedJson(candidate);break;- } catch {+ } catch (e) {+ if (e instanceof Error && e.message.startsWith("laya-ts: SHA-256 mismatch")) throw e;// Try the next supported Hugging Face layout.}}- return { dir: base, cfg, tokenizerJson };+ return { dir: base, cfg, tokenizerJson, revision };}export async function createNodeProvider(@@ -390,6 +492,11 @@ export async function createWebProvider(} catch {throw new Error(`Incompatible model: 'head.onnx' not found (expected ${headUrl}).`);}+ // Verify before the bytes reach the runtime: a tampered ONNX never becomes a session.+ if (opts?.expectedSha256) {+ await expectDigest("encoder.onnx", encBuf, opts.expectedSha256);+ await expectDigest("head.onnx", headBuf, opts.expectedSha256);+ }let enc: any;try {enc = await ort.InferenceSession.create(new Uint8Array(encBuf), {diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.tsindex 6153103e..cd7efdd2 100644--- a/laya-ts/src/router.ts+++ b/laya-ts/src/router.ts@@ -120,6 +120,8 @@ export interface RouterOptions {langGuess?: LangGuess;lang_guess?: LangGuess;loader?: AgentLoader;+ /** Optional hub revision (commit SHA/branch/tag) applied to every checkpoint load. */+ revision?: string | null;hooks?: HookArg;onPredictStart?: PredictHook;onPredictEnd?: PredictHook;@@ -154,6 +156,7 @@ export class Router extends HookRegistry {models: Record<string, ModelSpec>;device: string | null;token: string | null | undefined;+ revision: string | null;maxLoaded: number;default: ModelName;autoTaskDetection: boolean;@@ -179,6 +182,9 @@ export class Router extends HookRegistry {}this.device = opts.device ?? null;this.token = opts.token ?? (typeof process !== "undefined" ? process.env?.["HF_TOKEN"] : undefined);+ // Optional hub revision applied to every checkpoint load; published checkpoints pin+ // to a reviewed SHA even without it (see PINNED_REVISIONS in providers.ts).+ this.revision = opts.revision ?? null;this.maxLoaded = Math.max(1, Math.trunc(Number(opts.maxLoaded ?? opts.max_loaded ?? 2)));this.default = normaliseName(opts.default ?? "english");this.autoTaskDetection = Boolean(opts.autoTaskDetection ?? opts.auto_task_detection ?? false);@@ -209,6 +215,7 @@ export class Router extends HookRegistry {subfolder: spec.subfolder,device: this.device ?? undefined,token: this.token ?? undefined,+ revision: this.revision ?? undefined,});}this._agents.set(key, agent);diff --git a/laya-ts/tests/revision-pinning.test.ts b/laya-ts/tests/revision-pinning.test.tsnew file mode 100644index 00000000..90188ca7--- /dev/null+++ b/laya-ts/tests/revision-pinning.test.ts@@ -0,0 +1,147 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { createHash } from "node:crypto";+import * as fs from "node:fs";+import * as os from "node:os";+import * as path from "node:path";+import { Agent } from "../src/agent.js";+import { Router } from "../src/router.js";+import { PINNED_REVISIONS, loadNodeBundle, resolveRevision } from "../src/providers.js";++const fakeProvider = () => ({+ async runEncoder(_b: any) { return { lastHidden: [[1, 0], [0, 1]] }; },+ async runHead(_h: any) { return { logits: [[2, 0]], act: [[3, 0]] }; },+});++class StubResponse {+ constructor(public body: Uint8Array | null, public status = 200) {}+ get ok() { return this.status >= 200 && this.status < 300; }+ headers = { get: (n: string) => (n === "x-repo-commit" ? "abc123" : null) };+ async arrayBuffer() { return (this.body ?? new Uint8Array()).buffer as ArrayBuffer; }+}++const tmpDirs: string[] = [];+function makeCheckpoint(files: Record<string, Uint8Array>): string {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "laya-rev-"));+ tmpDirs.push(dir);+ for (const [rel, data] of Object.entries(files)) {+ const p = path.join(dir, rel);+ fs.mkdirSync(path.dirname(p), { recursive: true });+ fs.writeFileSync(p, data);+ }+ return dir;+}+const cfgFile = { "rl_agent_config.json": new TextEncoder().encode('{"act_costs":{"a":0}}') };+const sha256 = (b: Uint8Array) => createHash("sha256").update(b).digest("hex");++afterEach(() => {+ vi.unstubAllGlobals();+ for (const d of tmpDirs.splice(0)) fs.rmSync(d, { recursive: true, force: true });+});++describe("resolveRevision", () => {+ it("explicit revision wins over the pin", () => {+ expect(resolveRevision("convaiinnovations/laya", "abc123")).toBe("abc123");+ });+ it("published repos fall back to the reviewed pin", () => {+ for (const [repo, sha] of Object.entries(PINNED_REVISIONS)) {+ expect(sha).toMatch(/^[0-9a-f]{40}$/);+ expect(resolveRevision(repo)).toBe(sha);+ }+ });+ it("unknown repos keep the hub default", () => {+ expect(resolveRevision("acme/custom-model")).toBeNull();+ });+});++describe("loadNodeBundle pinning", () => {+ it("fetches published checkpoints at the pinned revision and joins it to the cache key", async () => {+ const urls: string[] = [];+ vi.stubGlobal("fetch", vi.fn(async (url: string) => {+ urls.push(url);+ return url.endsWith("rl_agent_config.json")+ ? new StubResponse(cfgFile["rl_agent_config.json"])+ : new StubResponse(null, 404);+ }));+ const pin = PINNED_REVISIONS["convaiinnovations/laya"];+ const cacheDir = path.join(os.homedir(), ".cache", "laya-ts", "hf", "convaiinnovations__laya", "root", pin);+ try {+ const bundle = await loadNodeBundle("convaiinnovations/laya");+ expect(urls[0]).toContain(`/resolve/${pin}/`);+ expect(bundle.dir).toBe(cacheDir);+ // The hub reports the exact commit served; that wins over the requested pin.+ expect(bundle.revision).toBe("abc123");+ expect(bundle.cfg.act_costs).toEqual({ a: 0 });+ } finally {+ fs.rmSync(path.join(os.homedir(), ".cache", "laya-ts", "hf", "convaiinnovations__laya"), { recursive: true, force: true });+ }+ });++ it("unpinned repos keep the mutable main default", async () => {+ const urls: string[] = [];+ vi.stubGlobal("fetch", vi.fn(async (url: string) => {+ urls.push(url);+ return url.endsWith("rl_agent_config.json")+ ? new StubResponse(cfgFile["rl_agent_config.json"])+ : new StubResponse(null, 404);+ }));+ try {+ await loadNodeBundle("acme/custom-model");+ expect(urls[0]).toContain("/resolve/main/");+ } finally {+ fs.rmSync(path.join(os.homedir(), ".cache", "laya-ts", "hf", "acme__custom-model"), { recursive: true, force: true });+ }+ });+});++describe("loadNodeBundle expectedSha256", () => {+ it("local dirs never download and report no revision", async () => {+ const fetchSpy = vi.fn();+ vi.stubGlobal("fetch", fetchSpy);+ const dir = makeCheckpoint(cfgFile);+ const bundle = await loadNodeBundle(dir);+ expect(fetchSpy).not.toHaveBeenCalled();+ expect(bundle.revision).toBeNull();+ });++ it("matching digests pass; unlisted artifacts are unchecked", async () => {+ const weights = new TextEncoder().encode("weights");+ const dir = makeCheckpoint({ ...cfgFile, "model.bin": weights });+ const bundle = await loadNodeBundle(dir, {+ expectedSha256: { "model.bin": sha256(weights) },+ });+ expect(bundle.dir).toBe(dir);+ });++ it("mismatches refuse to load", async () => {+ const dir = makeCheckpoint({ ...cfgFile, "model.bin": new TextEncoder().encode("weights") });+ await expect(loadNodeBundle(dir, { expectedSha256: { "model.bin": "0".repeat(64) } }))+ .rejects.toThrow(/SHA-256 mismatch/);+ });++ it("missing artifacts refuse to load", async () => {+ const dir = makeCheckpoint(cfgFile);+ await expect(loadNodeBundle(dir, { expectedSha256: { "absent.bin": "0".repeat(64) } }))+ .rejects.toThrow(/cannot verify/);+ });++ it("escaping digest paths are rejected", async () => {+ const dir = makeCheckpoint(cfgFile);+ for (const rel of ["../evil", "..", "a/../../evil"]) {+ await expect(loadNodeBundle(dir, { expectedSha256: { [rel]: "0".repeat(64) } }))+ .rejects.toThrow(/unsafe path/);+ }+ });+});++describe("revision plumbing", () => {+ it("Agent keeps the revision from its options", () => {+ const agent = new Agent({ provider: fakeProvider(), cfg: {}, revision: "abc123" });+ expect(agent.revision).toBe("abc123");+ expect(new Agent({ provider: fakeProvider(), cfg: {} }).revision).toBeNull();+ });++ it("Router stores an explicit revision", () => {+ expect(new Router({ revision: "abc123" }).revision).toBe("abc123");+ expect(new Router().revision).toBeNull();+ });+});diff --git a/laya/agent.py b/laya/agent.pyindex a76041f7..c16f7169 100644--- a/laya/agent.py+++ b/laya/agent.py@@ -28,6 +28,7 @@ from .common import (temp_bucket,)from .hooks import HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks+from .revisions import resolve_revision, snapshot_revision, verify_digestsdef _fix_tokenizer_config(path: str):@@ -216,6 +217,8 @@ class Agent(HookRegistry):subfolder: Optional[str] = None,fast: bool = False,compile: bool = False,+ revision: Optional[str] = None,+ expected_sha256: Optional[Dict[str, str]] = None,lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,hooks=None,on_predict_start=None,@@ -225,6 +228,14 @@ class Agent(HookRegistry):):"""Load a Laya checkpoint.+ `revision` pins the Hub download to an explicit commit SHA/branch/tag. The+ published convaiinnovations/* checkpoints default to the reviewed SHA pinned in+ `laya.revisions.PINNED_REVISIONS` instead of mutable `main`; pass `revision` to+ override. `expected_sha256` ({path relative to the checkpoint dir: hexdigest})+ verifies artifact integrity before any weight is parsed or executed; it is opt-in+ and applies to local directories too. A missing artifact or digest mismatch raises+ `ValueError` and loading is refused.+`fast=True` swaps the encoder/head forward for the TileLang fast path (CUDA only, needs`pip install laya[fast]`); see `Agent.accelerate`.@@ -250,6 +261,7 @@ class Agent(HookRegistry):from transformers.modeling_utils import no_init_weightsmodel_dir = model_id_or_path+ self.revision: Optional[str] = Noneif not os.path.exists(model_dir):if model_id_or_path.startswith(("/", "./", "../")) or os.path.isabs(model_id_or_path):raise FileNotFoundError(@@ -260,6 +272,7 @@ class Agent(HookRegistry):# Restrict root checkpoints too: the default repo also contains sibling# checkpoints, which an unfiltered snapshot would unnecessarily download.+ revision = resolve_revision(model_id_or_path, revision)prefix = f"{subfolder}/" if subfolder else ""kw = {"token": token or os.environ.get("HF_TOKEN") or None,@@ -267,7 +280,11 @@ class Agent(HookRegistry):"rl_agent_config.json", "model.safetensors", "tokenizer/*", "encoder/*",)],}+ if revision:+ kw["revision"] = revisionmodel_dir = snapshot_download(model_id_or_path, **kw)+ # The cache layout records which commit the snapshot points at.+ self.revision = snapshot_revision(model_dir) or revisionif subfolder:model_dir = os.path.join(model_dir, subfolder)@@ -276,6 +293,10 @@ class Agent(HookRegistry):f"Subfolder {subfolder!r} not found in {model_id_or_path!r}.")+ # Verify integrity before any file in the checkpoint is parsed or executed.+ if expected_sha256:+ verify_digests(model_dir, expected_sha256)+_fix_tokenizer_config(model_dir)cfg_path = os.path.join(model_dir, "rl_agent_config.json")@@ -920,6 +941,7 @@ RLAgent = Agentdef load(model_id_or_path: str = "convaiinnovations/laya", device: Optional[str] = None,token: Optional[str] = None, subfolder: Optional[str] = None, fast: bool = False,+ revision: Optional[str] = None, expected_sha256: Optional[Dict[str, str]] = None,lang_temperatures: Optional[Dict[str, Dict[str, Any]]] = None,hooks=None, on_predict_start=None, on_predict_end=None,hooks_raise: bool = True, hooks_concurrent: bool = True) -> Agent:@@ -931,10 +953,12 @@ def load(model_id_or_path: str = "convaiinnovations/laya", device: Optional[str]laya.load("convaiinnovations/laya", subfolder="multilingual")laya.load("convaiinnovations/laya", fast=True) # TileLang GPU fast path+ `revision`/`expected_sha256` pin and verify the downloaded artifacts; see `Agent`.`hooks` / `on_predict_start` / `on_predict_end` observe or shape every prediction; see`laya.hooks`."""return Agent(model_id_or_path, device=device, token=token, subfolder=subfolder, fast=fast,+ revision=revision, expected_sha256=expected_sha256,lang_temperatures=lang_temperatures,hooks=hooks, on_predict_start=on_predict_start, on_predict_end=on_predict_end,hooks_raise=hooks_raise, hooks_concurrent=hooks_concurrent)diff --git a/laya/common.py b/laya/common.pyindex 683b8a45..aac9507f 100644--- a/laya/common.py+++ b/laya/common.py@@ -206,7 +206,8 @@ def _apply_rope_config(ecfg) -> None:setattr(ecfg, attr, float(theta))-def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool = True) -> DecisionModel:+def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool = True,+ revision: Optional[str] = None) -> DecisionModel:from transformers import AutoConfig, AutoModelif not pretrained or (encoder_dir and os.path.exists(encoder_dir)):@@ -214,7 +215,11 @@ def build_model(cfg: Dict, encoder_dir: Optional[str] = None, pretrained: bool =_apply_rope_config(ecfg)enc = AutoModel.from_config(ecfg, attn_implementation="sdpa")else:- enc = AutoModel.from_pretrained(cfg["encoder"], attn_implementation="sdpa")+ # Training-time Hub load of the base encoder; allow pinning it like the checkpoints.+ kw = {"attn_implementation": "sdpa"}+ if revision:+ kw["revision"] = revision+ enc = AutoModel.from_pretrained(cfg["encoder"], **kw)return DecisionModel(enc, cfg.get("head_layers", 2), len(cfg.get("act_costs", {})) + 1)diff --git a/laya/onnx_agent.py b/laya/onnx_agent.pyindex 52326404..986076d0 100644--- a/laya/onnx_agent.py+++ b/laya/onnx_agent.py@@ -8,6 +8,7 @@ from typing import Any, Dict, Optional, Unionimport numpy as npfrom laya.hooks import HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks+from laya.revisions import resolve_revision, snapshot_revision, verify_digestsfrom laya.common import (QTYPES,answer_confidence,@@ -38,6 +39,8 @@ class ONNXAgent(HookRegistry):model_id_or_path: str,onnx_path: str = "laya.onnx",subfolder: Optional[str] = None,+ revision: Optional[str] = None,+ expected_sha256: Optional[Dict[str, str]] = None,hooks=None,on_predict_start=None,on_predict_end=None,@@ -51,6 +54,13 @@ class ONNXAgent(HookRegistry):(used to load the tokenizer and config).onnx_path: Path to the exported .onnx file.subfolder: Optional subfolder if downloading from a repo bundle.+ revision: Optional Hub revision (commit SHA/branch/tag). Published+ convaiinnovations/* checkpoints default to the reviewed SHA pinned+ in `laya.revisions.PINNED_REVISIONS` instead of mutable `main`.+ expected_sha256: Optional {path relative to the checkpoint dir: hexdigest}+ verified before any checkpoint file is parsed; opt-in, and applies+ to local directories too. A missing artifact or digest mismatch+ raises `ValueError` and loading is refused.hooks (HookArg): Opt-in prediction hooks; see `laya.hooks`.on_predict_start (PredictHookArg): An opt-in start hook, run before inference.on_predict_end (PredictHookArg): An opt-in end hook, run after inference.@@ -68,6 +78,7 @@ class ONNXAgent(HookRegistry):from transformers import AutoTokenizermodel_dir = model_id_or_path+ self.revision: Optional[str] = Noneif not os.path.exists(model_dir):if model_id_or_path.startswith(("/", "./", "../")) or os.path.isabs(model_id_or_path):raise FileNotFoundError(@@ -75,13 +86,17 @@ class ONNXAgent(HookRegistry):)from huggingface_hub import snapshot_download+ revision = resolve_revision(model_id_or_path, revision)prefix = f"{subfolder}/" if subfolder else ""kw = {"allow_patterns": [prefix + name for name in ("rl_agent_config.json", "tokenizer/*", "encoder/*",)],}+ if revision:+ kw["revision"] = revisionmodel_dir = snapshot_download(model_id_or_path, **kw)+ self.revision = snapshot_revision(model_dir) or revisionif subfolder:model_dir = os.path.join(model_dir, subfolder)@@ -90,6 +105,10 @@ class ONNXAgent(HookRegistry):f"Subfolder {subfolder!r} not found in {model_id_or_path!r}.")+ # Verify integrity before any file in the checkpoint is parsed or executed.+ if expected_sha256:+ verify_digests(model_dir, expected_sha256)+cfg_path = os.path.join(model_dir, "rl_agent_config.json")if not os.path.exists(cfg_path):raise FileNotFoundError(diff --git a/laya/revisions.py b/laya/revisions.pynew file mode 100644index 00000000..58863440--- /dev/null+++ b/laya/revisions.py@@ -0,0 +1,71 @@+"""Supply-chain integrity for published checkpoints: pinned revisions and digest checks.++Runtime loaders default to the mutable ``main`` revision of a Hub repo. For the published+checkpoints that is a silent-behavior-change risk: a compromised or accidentally changed+model repository would change routing, confidence, guardrail, and ONNX behavior with no+code change on the user's side. Loading a published repo without an explicit revision+therefore pins to the reviewed commit SHA below, and any loader accepts an optional+SHA-256 map to verify artifact integrity before weights reach the runtime.+"""+import hashlib+import os+from typing import Dict, Optional++# Reviewed commit SHAs of the published checkpoints. Bump a pin only after the new+# revision has been reviewed; treat an unexpected upstream SHA change as a prompt to+# review, not to blindly re-pin.+PINNED_REVISIONS: Dict[str, str] = {+ "convaiinnovations/laya": "55cf4c4ebb4ebe31b2550e8bdf3bd21b99753851",+ "convaiinnovations/laya-multilingual": "e4e9ddf21a7b1903b7acffd8814ad4307bf63a67",+ "convaiinnovations/laya-typed-decisions": "1a793eb568e6718f15941d08f85432581df534e3",+}+++def resolve_revision(model_id_or_path: str, revision: Optional[str] = None) -> Optional[str]:+ """Pick the revision to download.++ An explicit `revision` always wins; a published repo falls back to its reviewed pin;+ anything else returns None so the Hub default (`main`) applies unchanged.+ """+ if revision:+ return revision+ return PINNED_REVISIONS.get(model_id_or_path)+++def snapshot_revision(path: str) -> Optional[str]:+ """Commit SHA a Hub snapshot directory points at, or None for a plain directory.++ `snapshot_download` returns ``<cache>/snapshots/<sha>``; resolving symlinks keeps this+ correct when the snapshot entry is a link into the blob store.+ """+ real = os.path.realpath(path).rstrip(os.sep)+ parent, base = os.path.split(real)+ if os.path.basename(parent) == "snapshots" and base:+ return base+ return None+++def verify_digests(model_dir: str, expected: Dict[str, str]) -> None:+ """Verify SHA-256 digests of files under `model_dir` against {relpath: hexdigest}.++ Raises FileNotFoundError when a listed file is absent and ValueError on a digest+ mismatch or an unsafe (absolute or escaping) relative path. Verification runs before+ any weight is parsed or executed, so a tampered artifact never reaches the runtime.+ """+ for rel, want in expected.items():+ rel_norm = str(rel).replace("\\", "/").lstrip("/")+ if not rel_norm or rel_norm == ".." or rel_norm.startswith("../") or "/../" in rel_norm:+ raise ValueError("laya: unsafe path in expected digests: %r" % (rel,))+ path = os.path.join(model_dir, rel_norm)+ if not os.path.isfile(path):+ raise FileNotFoundError(+ "laya: cannot verify %r: no such file under %s" % (rel, model_dir))+ digest = hashlib.sha256()+ with open(path, "rb") as f:+ for chunk in iter(lambda: f.read(1 << 20), b""):+ digest.update(chunk)+ got = digest.hexdigest()+ if got.lower() != str(want).strip().lower():+ raise ValueError(+ "laya: SHA-256 mismatch for %s: expected %s, got %s. The artifact does "+ "not match the reviewed digest; refusing to load it." % (rel, want, got))diff --git a/laya/router.py b/laya/router.pyindex 91920c08..556bbfd8 100644--- a/laya/router.py+++ b/laya/router.py@@ -214,6 +214,7 @@ class Router(HookRegistry):models: Optional[Dict[str, str]] = None,device: Optional[str] = None,token: Optional[str] = None,+ revision: Optional[str] = None,max_loaded: int = 2,default: str = "english",auto_task_detection: bool = False,@@ -236,6 +237,10 @@ class Router(HookRegistry):self.models.update({normalise_name(k): v for k, v in models.items()})self.device = deviceself.token = token or os.environ.get("HF_TOKEN")+ # Optional Hub revision (commit SHA/branch/tag) applied to every checkpoint load.+ # The published checkpoints pin to a reviewed SHA even without this; see+ # `laya.revisions.PINNED_REVISIONS`.+ self.revision = revisionself.max_loaded = max(1, int(max_loaded))self.default = normalise_name(default)self.auto_task_detection = bool(auto_task_detection)@@ -267,7 +272,8 @@ class Router(HookRegistry):return self._agents[key]from .agent import Agentrepo, sub = _split(self.models[key])- agent = Agent(repo, device=self.device, token=self.token, subfolder=sub)+ agent = Agent(repo, device=self.device, token=self.token, subfolder=sub,+ revision=self.revision)self._agents[key] = agentself._order.append(key)evicted = self._evict_locked()@@ -381,6 +387,12 @@ class Router(HookRegistry):with self._lock:return list(self._order)+ @property+ def loaded_revisions(self) -> Dict[str, Optional[str]]:+ """Commit SHA each resident agent was loaded from (None for local paths)."""+ with self._lock:+ return {name: getattr(agent, "revision", None) for name, agent in self._agents.items()}+def _resolve_hint(self, hint: Any, state: Union[str, dict, list, None]) -> Optional[bool]:"""True/False for a hint about whether the English checkpoint can read `state`.diff --git a/laya/serve.py b/laya/serve.pyindex afecb966..8e73a93d 100644--- a/laya/serve.py+++ b/laya/serve.py@@ -242,6 +242,7 @@ def create_app(router: Optional[Any] = None):return {"status": "ok","loaded": router.loaded,+ "revisions": router.loaded_revisions,"device": os.environ.get("LAYA_DEVICE") or "auto",}diff --git a/tests/test_revision_pinning.py b/tests/test_revision_pinning.pynew file mode 100644index 00000000..a0f8b55f--- /dev/null+++ b/tests/test_revision_pinning.py@@ -0,0 +1,142 @@+"""Revision pinning and digest verification tests; no network required.++Run: python tests/test_revision_pinning.py+"""+import hashlib+import json+import os+from pathlib import Path+import sys+import tempfile+import unittest+from types import SimpleNamespace+from unittest.mock import patch++os.environ.setdefault("USE_TF", "0")+os.environ.setdefault("USE_TORCH", "1")+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))++from laya.agent import Agent # noqa: E402+from laya.revisions import ( # noqa: E402+ PINNED_REVISIONS,+ resolve_revision,+ snapshot_revision,+ verify_digests,+)+from laya.router import Router # noqa: E402+++class _StopLoad(Exception):+ """Sentinel raised by the fake snapshot_download once kwargs are captured."""+++def _capturing_snapshot(captured):+ def fake_snapshot(repo_id, **kwargs):+ captured.update(kwargs)+ raise _StopLoad+ return fake_snapshot+++class ResolveRevisionTests(unittest.TestCase):+ def test_explicit_revision_wins(self):+ self.assertEqual(resolve_revision("convaiinnovations/laya", "abc123"), "abc123")++ def test_published_repos_fall_back_to_the_pin(self):+ for repo, sha in PINNED_REVISIONS.items():+ self.assertEqual(resolve_revision(repo), sha)+ self.assertTrue(all(c in "0123456789abcdef" for c in sha), repo)+ self.assertEqual(len(sha), 40, repo)++ def test_unknown_repo_keeps_the_hub_default(self):+ self.assertIsNone(resolve_revision("acme/custom-model"))+ self.assertIsNone(resolve_revision("acme/custom-model", ""))+++class SnapshotRevisionTests(unittest.TestCase):+ def test_snapshot_layout(self):+ self.assertEqual(snapshot_revision("/cache/models--a--b/snapshots/deadbeef"), "deadbeef")++ def test_plain_directory(self):+ self.assertIsNone(snapshot_revision("/plain/dir"))+ self.assertIsNone(snapshot_revision(""))+++class VerifyDigestsTests(unittest.TestCase):+ def setUp(self):+ self.tmp = tempfile.TemporaryDirectory()+ self.dir = self.tmp.name+ with open(os.path.join(self.dir, "weights.bin"), "wb") as f:+ f.write(b"weights")+ self.digest = hashlib.sha256(b"weights").hexdigest()++ def tearDown(self):+ self.tmp.cleanup()++ def test_matching_digest_passes(self):+ verify_digests(self.dir, {"weights.bin": self.digest})+ verify_digests(self.dir, {"weights.bin": self.digest.upper()})++ def test_mismatch_raises(self):+ with self.assertRaises(ValueError):+ verify_digests(self.dir, {"weights.bin": "0" * 64})++ def test_missing_file_raises(self):+ with self.assertRaises(FileNotFoundError):+ verify_digests(self.dir, {"absent.bin": self.digest})++ def test_escaping_paths_rejected(self):+ for rel in ("../evil", "..", "a/../../evil", "\\..\\evil"):+ with self.assertRaises(ValueError, msg=rel):+ verify_digests(self.dir, {rel: self.digest})+++class AgentPinningTests(unittest.TestCase):+ def test_hub_load_pins_published_repo(self):+ captured = {}+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):+ with self.assertRaises(_StopLoad):+ Agent("convaiinnovations/laya")+ self.assertEqual(captured["revision"], PINNED_REVISIONS["convaiinnovations/laya"])++ def test_explicit_revision_overrides_the_pin(self):+ captured = {}+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):+ with self.assertRaises(_StopLoad):+ Agent("convaiinnovations/laya", revision="abc123")+ self.assertEqual(captured["revision"], "abc123")++ def test_unpinned_repo_gets_no_revision_kwarg(self):+ captured = {}+ with patch("huggingface_hub.snapshot_download", _capturing_snapshot(captured)):+ with self.assertRaises(_StopLoad):+ Agent("acme/custom-model")+ self.assertNotIn("revision", captured)++ def test_local_path_never_downloads(self):+ with tempfile.TemporaryDirectory() as tmp:+ with patch("huggingface_hub.snapshot_download") as download:+ with self.assertRaises(FileNotFoundError):+ Agent(tmp)+ download.assert_not_called()++ def test_digest_mismatch_raises_before_weights_load(self):+ with tempfile.TemporaryDirectory() as tmp:+ (Path(tmp) / "rl_agent_config.json").write_text(json.dumps({"act_costs": {"a": 0}}))+ (Path(tmp) / "model.safetensors").write_bytes(b"not the reviewed weights")+ with self.assertRaises(ValueError):+ Agent(tmp, expected_sha256={"model.safetensors": "0" * 64})+++class RouterRevisionTests(unittest.TestCase):+ def test_router_stores_an_explicit_revision(self):+ self.assertEqual(Router(revision="abc123").revision, "abc123")+ self.assertIsNone(Router().revision)++ def test_loaded_revisions_reports_resident_agents(self):+ router = Router()+ router.attach("english", SimpleNamespace(revision="sha-english"))+ self.assertEqual(router.loaded_revisions, {"english": "sha-english"})+++if __name__ == "__main__":+ unittest.main()