Skip to content

armgit / laya

Public Imported from GitHub
0

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.

fix(router): stop a per-checkpoint pin from silently disabling the caller's digest and revision

Adeshina Lasisi5bd0ed93701c
diff --git a/laya/router.py b/laya/router.py
index 36a0ec6d..418f3724 100644
--- a/laya/router.py
+++ b/laya/router.py
@@ -255,12 +255,14 @@ def _digests_from_env(models: Dict[str, Any]) -> Dict[str, Optional[Dict[str, st
the bundled repository ships a separate `model.safetensors` per checkpoint, so one flat
map can only ever match one of them and refuses the rest at startup.
- A checkpoint the nested map does not name is returned as `{}`, meaning deliberately
- unpinned: `Agent` falls back to the environment when given `None`, and reading a
- model-keyed map as an artifact map fails with `cannot verify 'english': no such file`.
+ A checkpoint the nested map does not name is returned as `{}`, meaning "not covered by this
+ variable, and do not let `verify_digests` read this nested map as an artifact map either" -- it
+ would fail with `cannot verify 'english': no such file` on a checkpoint the variable never
+ named. It needs no distinguishing from a `{}` somebody wrote: both name no files, and
+ `_merge_expected_digests` merges them identically.
Keys are normalised exactly as `Router(sha256_digests=...)` normalises them, so `en`
names `english` and a name core does not know raises here rather than quietly leaving
- that checkpoint unverified. Unset, empty or unparseable input returns `{}`:
+ that checkpoint unverified. Unset, empty or unparseable input names nothing:
`laya.revisions` reports a malformed value in its own words.
"""
raw = os.environ.get("LAYA_SHA256_DIGESTS", "").strip()
@@ -279,12 +281,83 @@ def _digests_from_env(models: Dict[str, Any]) -> Dict[str, Optional[Dict[str, st
raise ValueError("LAYA_SHA256_DIGESTS must be either {artifact: digest} for every "
"checkpoint or {model: {artifact: digest}} per checkpoint; %s mixes "
"the two or holds a value that is neither" % sorted(data))
- per_model = {normalise_name(k): v for k, v in data.items()}
+ per_model = {normalise_name(k): dict(v) for k, v in data.items()}
for name in models:
per_model.setdefault(normalise_name(name), {})
return per_model
+def _revision_pin(value: Optional[str]) -> Optional[str]:
+ """The revision `value` asks for, or None when it asks for nothing.
+
+ Unset and blank are the same answer, because both are what a configuration line that did not
+ get filled in leaves behind, and neither is a commit anything can be pinned to.
+ """
+ return value if value is not None and str(value).strip() else None
+
+
+def _digest_entry(
+ digests: Dict[str, Optional[Dict[str, str]]],
+ key: str,
+) -> Optional[Dict[str, str]]:
+ """One checkpoint's own digest entry, as `Router.sha256_digests` holds it right now.
+
+ None when the checkpoint has no entry at all, which is what leaves `verify_digests` its own
+ environment fallback; `{}` for an entry that names no files, whether that is the placeholder a
+ nested `LAYA_SHA256_DIGESTS` left or a `None` a caller wrote.
+
+ Read here rather than decided once at construction, because `sha256_digests` is a public mutable
+ attribute: a per-checkpoint pin assigned to it -- or added to an existing entry in place -- after
+ `Router(...)` has to count, and deciding from a key set frozen at construction dropped exactly
+ that.
+ """
+ if key not in digests:
+ return None
+ entry = digests[key]
+ return {} if entry is None else entry
+
+
+def _merge_expected_digests(
+ shared: Optional[Dict[str, str]],
+ per_model: Optional[Dict[str, str]],
+) -> Optional[Dict[str, str]]:
+ """The `expected_sha256` one checkpoint is built with, out of the two channels that pin it.
+
+ `shared` is `agent_kwargs["expected_sha256"]`, which the class docstring advertises and which
+ reaches every checkpoint the Router builds. `per_model` is this checkpoint's own entry: None when
+ it has none at all, and `{}` for the placeholder a nested `LAYA_SHA256_DIGESTS` leaves for a
+ checkpoint it does not name.
+
+ None -- both channels silent -- means "pass no `expected_sha256`", which leaves `verify_digests`
+ its own `LAYA_SHA256_DIGESTS` fallback and keeps an unconfigured load byte for byte what it was.
+ An empty `{}` is **not** the same thing and must still reach `Agent`: it masks that fallback,
+ which for a *nested* variable would otherwise be read as an artifact map and raise
+ `cannot verify 'english': no such file` on a checkpoint the variable never named.
+
+ A value that is not a mapping is handed on untouched, so `verify_digests` keeps ownership of the
+ "expected_sha256 must be a mapping" message rather than this layer growing a second copy.
+
+ The two channels are merged file by file, because each names files and a digest is a claim about
+ one file -- dropping either half would verify less than the caller asked for. **For a file both
+ name, the per-checkpoint entry wins.** They are not equally specific: `shared` reaches every
+ checkpoint, and `model.safetensors` is the one name every checkpoint uses for a *different* file,
+ so a shared entry for it cannot be a correct claim about all of them at once. Refusing that
+ overlap as a contradiction broke the ordinary shape it appears in -- a shared pin plus a
+ per-checkpoint override, which loaded correctly before this function existed.
+
+ An empty placeholder therefore needs no special case: merging it changes nothing.
+ """
+ if per_model is not None and not isinstance(per_model, dict):
+ return per_model
+ if shared is not None and not isinstance(shared, dict):
+ return shared
+ if shared is None and per_model is None:
+ return None
+ merged = dict(shared or {})
+ merged.update(per_model or {})
+ return merged
+
+
class Router(HookRegistry):
"""Lazily loads Laya checkpoints and sends each request to the right one.
@@ -318,6 +391,20 @@ class Router(HookRegistry):
which is useful when standalone repositories were reviewed at different commits.
Without either, huggingface_hub's normal default and existing offline cache are used.
+ A `revisions` entry that is `None` or blank is "no override for this model", so the model
+ inherits `revision` -- the shape `{"english": os.environ.get("EN_SHA")}` writes when the
+ variable is unset, which must not cost the caller the pin it did ask for. Nothing in
+ `revisions` can unpin one model while `revision` pins the rest; leave `revision` unset and
+ name the models you want pinned instead.
+
+ A blank `revision` is read the same way, which is a deliberate change in what the Router
+ passes on: `Router(revision=" ")` used to reach `resolve_revision`, where a truthy but blank
+ string suppressed the `LAYA_REVISION` fallback and left huggingface_hub's default, and is now
+ dropped before it gets there, so a Router configured with whitespace behaves like one
+ configured with nothing and `$LAYA_REVISION` applies. It is the one place a weaker source ends
+ up ahead of an explicit argument, and it is what "this configuration line was never filled in"
+ has to mean if `revision` and a `revisions` entry are to be read the same way.
+
Anything else `laya.Agent` accepts is reachable through `agent_kwargs`, which is merged into
every checkpoint the Router builds:
@@ -325,6 +412,23 @@ class Router(HookRegistry):
Router(agent_kwargs={"expected_sha256": {"model.safetensors": "a3f1..."}})
Router(agent_kwargs={"fast": True})
+ `expected_sha256` there pins the same files on every checkpoint, which is what a single
+ resident checkpoint or a shared `tokenizer.json` wants. It is never discarded wholesale: where a
+ checkpoint also has digests of its own, from `sha256_digests` or from the environment, the two
+ maps are merged **file by file**, so a file only one of them names is still verified.
+
+ For a file both name, the per-checkpoint entry wins. The two are not equally specific: the
+ `agent_kwargs` map reaches every checkpoint the Router builds, and `model.safetensors` is the one
+ name every checkpoint uses for a *different* file, so a shared entry for it cannot be a correct
+ claim about all of them at once. **Nothing raises over that overlap** -- refusing it would reject
+ a shared pin plus a per-checkpoint override, which is the ordinary shape and which loaded
+ correctly before any of this existed. If you need to know which digest a checkpoint was verified
+ against, read it back: the map handed to each `Agent` is the merge described above.
+
+ Both `agent_kwargs` and `sha256_digests` are public and mutable, and a checkpoint's entry is read
+ on the load rather than at construction, so a pin assigned in afterwards -- or added to an
+ existing entry in place -- counts.
+
The names the Router sets for itself -- `model_id_or_path`, `device`, `token`, `subfolder`,
`revision` and the hook arguments -- are refused here rather than silently shadowed, and the
remaining names are checked against `Agent.__init__` at construction, so a misspelled option
@@ -336,7 +440,9 @@ class Router(HookRegistry):
is no Router-wide equivalent of `revision` because digests, unlike a commit SHA, are not
shareable: the bundled repository ships a separate `model.safetensors` for each of
`english`, `multilingual` and `typed-decisions`, so one flat map can only ever match one
- of them. A model listed with `None` or `{}` is loaded unverified.
+ of them. A model listed with `None` or `{}` adds no files of its own, which loads it
+ unverified unless `agent_kwargs["expected_sha256"]` pins it; it still masks a flat
+ `LAYA_SHA256_DIGESTS`, which is what listing it that way is for.
The same split is available to a process configured only by environment: when
`LAYA_SHA256_DIGESTS` holds a model-keyed map (`{"english": {...}, "multilingual": {...}}`)
@@ -344,7 +450,10 @@ class Router(HookRegistry):
own digests instead of refusing to start on the second one. A flat `LAYA_SHA256_DIGESTS`
keeps its existing meaning, applied by `laya.revisions` to every checkpoint the process
loads, which is right for a single-checkpoint one. An argument entry wins over the
- environment for the model it names.
+ environment for the model it names. A nested variable that names some checkpoints and not
+ others says nothing about the others: they keep whatever `agent_kwargs["expected_sha256"]`
+ pins them with, because pinning one checkpoint from the environment is not a request to stop
+ verifying the rest.
Hooks are opt-in and run at the Router level: `on_route` sees the routing decision,
`on_load` / `on_evict` see model lifecycle, and `on_predict_start` / `on_predict_end`
@@ -409,9 +518,8 @@ class Router(HookRegistry):
# `revisions`, so a misspelled model name fails here rather than leaving that checkpoint
# unverified.
self.sha256_digests: Dict[str, Optional[Dict[str, str]]] = _digests_from_env(self.models)
- self.sha256_digests.update({
- normalise_name(k): v for k, v in (sha256_digests or {}).items()
- })
+ argument = {normalise_name(k): v for k, v in (sha256_digests or {}).items()}
+ self.sha256_digests.update(argument)
self.max_loaded = max(1, int(max_loaded))
self.default = normalise_name(default)
self.auto_task_detection = bool(auto_task_detection)
@@ -444,15 +552,21 @@ class Router(HookRegistry):
from .agent import Agent
repo, sub = _split(self.models[key])
kwargs = {"device": self.device, "token": self.token, "subfolder": sub}
- model_revision = self.revisions.get(key, self.revision)
+ # A None or blank entry in `revisions` is "no pin of its own", so the checkpoint
+ # inherits `revision`. Reading it as a pin of nothing dropped the caller's `revision`
+ # and handed that one checkpoint to `$LAYA_REVISION` instead, which is the opposite of
+ # what asking for a pin means.
+ model_revision = _revision_pin(self.revisions.get(key)) or _revision_pin(self.revision)
if model_revision is not None:
kwargs["revision"] = model_revision
- # Safe to merge last: the names this method just set are refused in `agent_kwargs`.
+ # Safe to merge last for the names above, which `agent_kwargs` refuses -- but not for
+ # `expected_sha256`, which is deliberately reachable through `agent_kwargs` and is
+ # therefore merged with this checkpoint's entry rather than replaced by it.
kwargs.update(self.agent_kwargs)
- if key in self.sha256_digests:
- # `or {}` is deliberate: an explicit None still has to reach Agent as a map, or
- # `verify_digests` would fall back to the environment default it is masking.
- kwargs["expected_sha256"] = self.sha256_digests[key] or {}
+ expected = _merge_expected_digests(kwargs.pop("expected_sha256", None),
+ _digest_entry(self.sha256_digests, key))
+ if expected is not None:
+ kwargs["expected_sha256"] = expected
agent = Agent(repo, **kwargs)
self._agents[key] = agent
self._order.append(key)
diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py
index ccd59572..348f78c0 100644
--- a/tests/test_hooks_api.py
+++ b/tests/test_hooks_api.py
@@ -83,6 +83,20 @@ check_param("Router.__init__", Router.__init__, "agent_kwargs", None)
# ...and the per-checkpoint digests that `revisions` has always had a sibling need for
check_param("Router.__init__", Router.__init__, "sha256_digests", None)
+# What the constructor does NOT raise over is part of its contract too: a shared
+# `agent_kwargs["expected_sha256"]` overlapping a per-checkpoint `sha256_digests` entry on one file
+# name is the ordinary shape, not a contradiction -- `model.safetensors` is the one name every
+# checkpoint uses for a different file. Refusing it here would reject a shared pin plus a
+# per-checkpoint override, and `laya.serve` maps a ValueError out of a load to a 422 about a
+# misconfiguration no request caused.
+_OVERLAP = "Router.__init__/a shared pin overlapping a per-checkpoint one constructs"
+try:
+ Router(sha256_digests={"english": {"model.safetensors": "b" * 64}},
+ agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}})
+ check_true(_OVERLAP, True, "constructed")
+except ValueError as exc:
+ check_true(_OVERLAP, False, "raised instead of constructing: %s" % exc)
+
# load() forwards Agent's own construction options, so none of them is reachable only
# through the class; tests/test_download.py asserts that against both signatures.
check_param("load", load, "compile", False)
diff --git a/tests/test_revision_pinning.py b/tests/test_revision_pinning.py
index ef8eafdc..0fe3274a 100644
--- a/tests/test_revision_pinning.py
+++ b/tests/test_revision_pinning.py
@@ -463,6 +463,30 @@ class RouterDigestEndToEndTests(unittest.TestCase):
def _env(self, per_model):
return patch.dict(os.environ, {"LAYA_SHA256_DIGESTS": json.dumps(per_model)})
+ # An `agent_kwargs` map is the third channel, and neither of the other two may cancel it:
+ # `expected_sha256` is reachable there on purpose, and a caller that pins a file is asking
+ # for it to be verified on every checkpoint this Router builds.
+ WRONG = {"model.safetensors": "0" * 64}
+
+ def test_agent_kwargs_still_refuses_a_checkpoint_the_environment_map_skips(self):
+ with self._env({"english": {"model.safetensors": self.digests["english"]}}):
+ router = self._router({}, agent_kwargs={"expected_sha256": self.WRONG})
+ with self.assertRaises(ValueError) as cm:
+ router.load("multilingual")
+ self.assertIn("SHA-256 mismatch", str(cm.exception))
+
+ def test_agent_kwargs_still_refuses_a_checkpoint_listed_as_none(self):
+ router = self._router({"multilingual": None}, agent_kwargs={"expected_sha256": self.WRONG})
+ with self.assertRaises(ValueError) as cm:
+ router.load("multilingual")
+ self.assertIn("SHA-256 mismatch", str(cm.exception))
+
+ def test_a_correct_agent_kwargs_digest_loads_under_the_same_configuration(self):
+ with self._env({"english": {"model.safetensors": self.digests["english"]}}):
+ router = self._router({}, agent_kwargs={
+ "expected_sha256": {"model.safetensors": self.digests["multilingual"]}})
+ self._assert_past_the_digest_gate(router, "multilingual")
+
class RouterEnvDigestTests(unittest.TestCase):
"""How `Router` reads the two shapes of `LAYA_SHA256_DIGESTS`.
@@ -544,5 +568,305 @@ class RouterEnvDigestTests(unittest.TestCase):
self.assertEqual(Router().sha256_digests, {}, value)
+class RouterDigestPrecedenceTests(unittest.TestCase):
+ """What reaches `Agent` when more than one channel pins the same checkpoint.
+
+ `expected_sha256` is deliberately *not* router-owned -- `test_accepted_names_are_read_from_
+ agent_rather_than_copied_here` asserts that, and the class docstring advertises
+ `Router(agent_kwargs={"expected_sha256": ...})` -- so a Router can hold digests from three
+ places at once: that argument, `sha256_digests`, and a nested `LAYA_SHA256_DIGESTS`. These
+ pin down that none of them silently turns another one off.
+ """
+
+ SHARED = {"tokenizer.json": "a" * 64}
+ PER_MODEL = {"model.safetensors": "b" * 64}
+
+ def setUp(self):
+ """Start every test from an unset `LAYA_SHA256_DIGESTS`.
+
+ Several checks here assert that *no* `expected_sha256` reaches `Agent`, which is only true of
+ an unconfigured process. A developer machine or CI runner that exports a **nested** variable --
+ the shape this feature exists to support -- seeds a `{}` placeholder for every model, so
+ `expected_sha256={}` is passed and those assertions fail with no code change. Tests that want
+ the variable set use `_env`.
+ """
+ patcher = patch.dict(os.environ, {}, clear=False)
+ patcher.start()
+ os.environ.pop("LAYA_SHA256_DIGESTS", None)
+ self.addCleanup(patcher.stop)
+
+ def _capture(self):
+ """Agent stand-in carrying the real signature, so `check_agent_kwargs` still applies."""
+ import inspect
+
+ import laya.agent
+
+ captured: list = []
+
+ class FakeAgent:
+ def __init__(self, repo, **kwargs):
+ captured.append(kwargs)
+
+ __init__.__signature__ = inspect.signature(Agent.__init__)
+
+ return patch.object(laya.agent, "Agent", FakeAgent), captured
+
+ def _env(self, per_model):
+ return patch.dict(os.environ, {"LAYA_SHA256_DIGESTS": json.dumps(per_model)})
+
+ def _load(self, name, **router_kwargs):
+ capture, captured = self._capture()
+ with capture:
+ Router(**router_kwargs).load(name)
+ return captured[0]
+
+ def test_a_nested_environment_pin_does_not_unverify_the_other_checkpoints(self):
+ # The variable names `english` only. `multilingual` is not mentioned by it, which is not
+ # the same as being asked for unverified: the caller's own map still has to apply.
+ with self._env({"english": {"model.safetensors": "e" * 64}}):
+ kwargs = self._load("multilingual", agent_kwargs={"expected_sha256": self.SHARED})
+ self.assertEqual(kwargs["expected_sha256"], self.SHARED)
+
+ def test_a_none_entry_does_not_discard_the_agent_kwargs_map(self):
+ kwargs = self._load("english", sha256_digests={"english": None},
+ agent_kwargs={"expected_sha256": self.SHARED})
+ self.assertEqual(kwargs["expected_sha256"], self.SHARED)
+
+ def test_the_two_maps_are_merged_file_by_file(self):
+ kwargs = self._load("english", sha256_digests={"english": self.PER_MODEL},
+ agent_kwargs={"expected_sha256": self.SHARED})
+ self.assertEqual(kwargs["expected_sha256"], dict(self.SHARED, **self.PER_MODEL))
+
+ def test_a_per_checkpoint_pin_wins_over_a_shared_one_for_the_same_file(self):
+ """The two channels are not equally specific, so the narrower one decides.
+
+ `agent_kwargs["expected_sha256"]` reaches every checkpoint, and `model.safetensors` is the
+ one name every checkpoint uses for a *different* file -- so a shared entry for it cannot be
+ a correct claim about all of them at once. An earlier version of this fix refused the
+ overlap as a contradiction, which broke the ordinary shape it appears in: a shared pin plus
+ a per-checkpoint override, which loaded correctly before any of this existed.
+ """
+ capture, captured = self._capture()
+ with capture:
+ router = Router(agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}},
+ sha256_digests={"multilingual": {"model.safetensors": "b" * 64}})
+ router.load("english")
+ router.load("multilingual")
+ self.assertEqual(captured[0]["expected_sha256"], {"model.safetensors": "c" * 64},
+ "the shared pin applies where nothing overrides it")
+ self.assertEqual(captured[1]["expected_sha256"], {"model.safetensors": "b" * 64},
+ "the per-checkpoint pin wins for the file both name")
+
+ def test_an_environment_pin_overrides_the_shared_one_per_checkpoint(self):
+ """Same precedence, reached through the variable, and every checkpoint stays loadable.
+
+ This is the shape that matters in a deployment: the variable pins each checkpoint's own
+ weight file and the caller passes one shared map. Refusing it would have stopped the server
+ from serving the checkpoint the two configurations do not actually disagree about.
+ """
+ capture, captured = self._capture()
+ shared = {"model.safetensors": "c" * 64}
+ with self._env({"english": {"model.safetensors": "b" * 64}}), capture:
+ router = Router(agent_kwargs={"expected_sha256": shared})
+ router.load("multilingual")
+ router.load("english")
+ self.assertEqual(captured[0]["expected_sha256"], shared,
+ "the checkpoint the variable does not name keeps the shared pin")
+ self.assertEqual(captured[1]["expected_sha256"], {"model.safetensors": "b" * 64},
+ "the checkpoint the variable names uses its own digest")
+
+ def test_files_only_one_channel_names_are_still_merged(self):
+ """Precedence applies per file, not per map: a file only one channel names still counts.
+
+ This is the half of the merge that is worth having -- the caller pins the tokenizer, the
+ deployment pins the weights, and the load verifies both. Ranking whole maps against each
+ other, as the code did before this fix, verified only one of them.
+ """
+ capture, captured = self._capture()
+ with self._env({"english": {"model.safetensors": "b" * 64}}), capture:
+ router = Router(agent_kwargs={"expected_sha256": {"tokenizer.json": "d" * 64}})
+ router.load("english")
+ self.assertEqual(captured[0]["expected_sha256"],
+ {"tokenizer.json": "d" * 64, "model.safetensors": "b" * 64},
+ "both channels' files must reach verify_digests")
+
+ def test_digests_added_into_an_environment_placeholder_in_place_are_verified(self):
+ """Filling in the placeholder the variable left is a pin, and has to be honoured.
+
+ `_digests_from_env` leaves an empty entry for every checkpoint a nested
+ `LAYA_SHA256_DIGESTS` does not name, tagged as "not something anyone asked for" so it cannot
+ cancel an `agent_kwargs` map. But `sha256_digests` is public: an operator may add digests to
+ that entry in place. Treating it as unpinned for ever dropped them silently -- and only when
+ an `agent_kwargs` map happened to be present, so the behaviour was config-dependent.
+ """
+ capture, captured = self._capture()
+ with self._env({"english": {"model.safetensors": "b" * 64}}), capture:
+ router = Router(agent_kwargs={"expected_sha256": {"tokenizer.json": "d" * 64}})
+ router.sha256_digests["multilingual"]["model.safetensors"] = "e" * 64
+ router.load("multilingual")
+ self.assertEqual(captured[0]["expected_sha256"],
+ {"tokenizer.json": "d" * 64, "model.safetensors": "e" * 64},
+ "a digest added into the placeholder must reach verify_digests")
+
+ def test_an_untouched_environment_placeholder_still_reaches_agent_as_an_empty_map(self):
+ """A placeholder must arrive as `{}`, NOT be omitted -- omitting it is a refusal.
+
+ This looks backwards until you run it: with a *nested* `LAYA_SHA256_DIGESTS` and no
+ `expected_sha256` kwarg at all, `verify_digests` reads that nested map as an artifact map and
+ raises `cannot verify 'english': no such file` -- on a checkpoint the variable never named.
+ The empty map is what masks that fallback. Passing nothing is only correct when no channel
+ said anything.
+ """
+ capture, captured = self._capture()
+ with self._env({"english": {"model.safetensors": "b" * 64}}), capture:
+ Router().load("multilingual")
+ self.assertEqual(captured[0].get("expected_sha256"), {},
+ "the placeholder must mask the nested-variable fallback")
+
+ # And with nothing configured anywhere, no kwarg is passed at all (#332).
+ capture2, captured2 = self._capture()
+ with capture2:
+ Router().load("multilingual")
+ self.assertNotIn("expected_sha256", captured2[0])
+
+ def test_an_explicit_none_entry_masks_a_flat_environment_map(self):
+ """`sha256_digests={"english": None}` means "load this one unverified", and has to hold.
+
+ A *flat* `LAYA_SHA256_DIGESTS` is applied by `verify_digests` itself, for every checkpoint.
+ Saying "not this one" therefore cannot be expressed by passing nothing -- that is exactly
+ what lets the flat map through. It has to arrive as an empty map.
+ """
+ flat = {"model.safetensors": "f" * 64}
+ for entry in (None, {}):
+ capture, captured = self._capture()
+ with self._env(flat), capture:
+ Router(sha256_digests={"english": entry}).load("english")
+ self.assertEqual(captured[0].get("expected_sha256"), {},
+ "an explicit %r entry must mask the flat variable" % (entry,))
+ # And with no entry at all the flat map is left to apply.
+ capture, captured = self._capture()
+ with self._env(flat), capture:
+ Router().load("english")
+ self.assertNotIn("expected_sha256", captured[0])
+
+ def test_a_pin_assigned_after_construction_wins_for_its_own_file(self):
+ """`sha256_digests` is public and mutable, so a pin assigned later has to take effect."""
+ capture, captured = self._capture()
+ with capture:
+ router = Router(agent_kwargs={"expected_sha256": {"model.safetensors": "c" * 64}})
+ router.sha256_digests["english"] = {"model.safetensors": "b" * 64}
+ router.load("english")
+ self.assertEqual(captured[0]["expected_sha256"], {"model.safetensors": "b" * 64})
+
+ def test_a_pin_added_after_construction_is_verified(self):
+ # `sha256_digests` is public and mutable, so what it holds at load time is what has to be
+ # verified. Deciding "somebody asked for this checkpoint" from a key set frozen in
+ # `__init__` dropped a later per-checkpoint pin -- and only when `agent_kwargs` happened
+ # to carry a map, which is the one configuration where the drop mattered.
+ capture, captured = self._capture()
+ with capture:
+ router = Router(agent_kwargs={"expected_sha256": self.SHARED})
+ router.sha256_digests["english"] = self.PER_MODEL
+ router.load("english")
+ self.assertEqual(captured[0]["expected_sha256"], dict(self.SHARED, **self.PER_MODEL))
+
+ def test_an_empty_map_assigned_after_construction_replaces_the_environment_entry(self):
+ """Assigning `{}` over an environment entry drops that entry's files.
+
+ What this pins is the *assignment*, not a placeholder/explicit distinction: `_digest_entry`
+ collapses a caller's `{}`, a caller's `None` and the placeholder to the same `{}` on purpose,
+ so there is nothing here that could tell them apart. The behaviour worth pinning is that the
+ entry the variable had put there is gone, which is why the shared map alone is the answer.
+ """
+ capture, captured = self._capture()
+ with self._env({"english": dict(self.PER_MODEL)}), capture:
+ router = Router(agent_kwargs={"expected_sha256": dict(self.SHARED)})
+ router.sha256_digests["english"] = {}
+ router.load("english")
+ self.assertEqual(captured[0]["expected_sha256"], self.SHARED,
+ "the assigned empty map must replace the variable's entry")
+
+ def test_the_environment_entries_still_read_as_plain_maps(self):
+ # How the placeholder is marked is this module's business: `sha256_digests` is public, and
+ # `RouterEnvDigestTests` reads it as plain dicts.
+ with self._env({"english": {"model.safetensors": "e" * 64}}):
+ digests = Router().sha256_digests
+ self.assertEqual(digests, {"english": {"model.safetensors": "e" * 64},
+ "multilingual": {}, "typed-decisions": {}})
+
+ def test_the_same_digest_from_both_channels_is_not_a_conflict(self):
+ both = {"model.safetensors": "b" * 64}
+ kwargs = self._load("english", sha256_digests={"english": both},
+ agent_kwargs={"expected_sha256": {"model.safetensors": "B" * 64}})
+ self.assertEqual({k: v.lower() for k, v in kwargs["expected_sha256"].items()}, both)
+
+ def test_nothing_configured_still_passes_no_map_at_all(self):
+ # #332's opt-in guarantee: an unconfigured Router must leave `verify_digests` its own
+ # `LAYA_SHA256_DIGESTS` fallback, so an existing HF_HUB_OFFLINE=1 cache loads as before.
+ self.assertNotIn("expected_sha256", self._load("english"))
+
+
+class RouterRevisionFallbackTests(unittest.TestCase):
+ """A `revisions` entry that names no commit must not cost the caller the pin it did ask for.
+
+ `revisions` is typed `Optional[Dict[str, Optional[str]]]`, so `None` values are legal, and
+ `{"english": os.environ.get("EN_SHA")}` produces one whenever that variable is unset.
+ """
+
+ def _capture(self):
+ import inspect
+
+ import laya.agent
+
+ captured: list = []
+
+ class FakeAgent:
+ def __init__(self, repo, **kwargs):
+ captured.append(kwargs)
+
+ __init__.__signature__ = inspect.signature(Agent.__init__)
+
+ return patch.object(laya.agent, "Agent", FakeAgent), captured
+
+ def _load(self, name="english", env="", **router_kwargs):
+ capture, captured = self._capture()
+ with patch.dict(os.environ, {"LAYA_REVISION": env}), capture:
+ Router(**router_kwargs).load(name)
+ return captured[0]
+
+ def _effective(self, kwargs, env=""):
+ """What `Agent` would download: `resolve_revision` applied to the kwarg it was handed."""
+ with patch.dict(os.environ, {"LAYA_REVISION": env}):
+ return resolve_revision("convaiinnovations/laya", kwargs.get("revision"))
+
+ def test_a_none_entry_inherits_the_router_wide_revision(self):
+ kwargs = self._load(revision="aaa", revisions={"english": None})
+ self.assertEqual(kwargs["revision"], "aaa")
+
+ def test_a_none_entry_does_not_hand_the_checkpoint_to_the_environment(self):
+ kwargs = self._load(revision="aaa", revisions={"english": None}, env="bbb")
+ self.assertEqual(self._effective(kwargs, env="bbb"), "aaa")
+
+ def test_a_blank_entry_is_read_the_same_way(self):
+ for blank in ("", " "):
+ kwargs = self._load(revision="aaa", revisions={"english": blank}, env="bbb")
+ self.assertEqual(self._effective(kwargs, env="bbb"), "aaa", blank)
+
+ def test_a_blank_router_wide_revision_is_not_a_pin(self):
+ self.assertNotIn("revision", self._load(revision=" "))
+
+ def test_an_explicit_per_model_revision_still_wins(self):
+ kwargs = self._load("multilingual", revision="aaa",
+ revisions={"multilingual": "ccc", "english": None}, env="bbb")
+ self.assertEqual(kwargs["revision"], "ccc")
+
+ def test_an_unconfigured_router_still_leaves_the_revision_to_the_environment(self):
+ # The other half of #332: nothing asked for means the deployment's `LAYA_REVISION` (or
+ # huggingface_hub's default) applies, exactly as it does for a hand-built `Agent`.
+ kwargs = self._load(env="bbb")
+ self.assertNotIn("revision", kwargs)
+ self.assertEqual(self._effective(kwargs, env="bbb"), "bbb")
+
+
if __name__ == "__main__":
unittest.main()