diff --git a/docs/api/model.md b/docs/api/model.md index 2180673..1db8d75 100644 --- a/docs/api/model.md +++ b/docs/api/model.md @@ -74,6 +74,53 @@ config = ModelConfig.from_preset("prism-olmo3-7b") model = UnifiedTransformer(config) ``` +## Backend metadata contract (version 1) + +`src.backends` provides metadata/discovery/resolution only. It imports only the +standard library and never constructs a model, imports torch/transformers, +fetches assets, or contacts a network. There is no automatic execution +integration: callers explicitly pass the selectors to `resolve_backend`. + +```python +from src.backends import describe_backend, list_backends, resolve_backend + +list_backends() # ("local_ar", "hf_ar", "u2_reference", "u2_native") +describe_backend("u2_native").status # "planned" (discovery is allowed) +resolve_backend(required_capabilities=("causal_forward",)).name # "local_ar" +resolve_backend(llm_backbone_id="allenai/Olmo-3-7B-Instruct").name # "hf_ar" +``` + +`BackendDescriptor` is frozen, with `name`, `contract_version=1`, immutable +`frozenset[str]` capabilities, and `status` (`"existing"` or `"planned"`). +The builtin registry is immutable; `list_backends()` returns its names as a +tuple in the order shown above. `describe_backend(name)` returns a descriptor. + +| Backend | Status | Capabilities | +|---------|--------|--------------| +| `local_ar` | existing | `causal_forward` | +| `hf_ar` | existing | `causal_forward`, `autoregressive_generate` | +| `u2_reference` | planned | none | +| `u2_native` | planned | none | + +`resolve_backend(*, backend=None, llm_backbone_id=None, contract_version=1, +required_capabilities=())` returns a descriptor. Default selection follows +the current `llm_backbone_id` truthiness: `None` or `""` selects local; any +nonempty string selects HF. It does not validate the model ID or availability. +Legacy `hf_model_id` is a weight-initialization field, not a selector; presets +that set only that field still resolve to local. Explicit `hf_ar` requires a +nonempty backbone ID; explicit `local_ar` with a nonempty ID raises `ValueError`. +Malformed/unknown selectors, versions other than integer 1 (including `True`), +and unknown/unsupported capability requests also raise `ValueError`. Capabilities +are an iterable of names, not a bare string or mapping. Planned U2 resolution +raises `NotImplementedError` without fallback; malformed or unknown capability +requests are rejected first. + +Local `UnifiedTransformer.generate()` currently returns `None`, so local +generation is not advertised. This contract makes no modality, structured +decoder, diffusion, training, quality, or accelerator/XPU validation claims, +and provides no pretrained U2 functionality. Existing construction, Hydra keys, +`ModelConfig`, checkpoint keys, and APIs are unchanged; no migration is required. + ## Decoders `src/decoders/` — the output side, registered by name in `DECODERS` diff --git a/src/backends/__init__.py b/src/backends/__init__.py new file mode 100644 index 0000000..3cbf2ea --- /dev/null +++ b/src/backends/__init__.py @@ -0,0 +1,6 @@ +"""Dependency-free backend metadata; importing this package never loads a model.""" + +from .capabilities import describe_backend, list_backends, resolve_backend +from .contracts import BackendDescriptor + +__all__ = ("BackendDescriptor", "list_backends", "describe_backend", "resolve_backend") diff --git a/src/backends/capabilities.py b/src/backends/capabilities.py new file mode 100644 index 0000000..1c63dd7 --- /dev/null +++ b/src/backends/capabilities.py @@ -0,0 +1,91 @@ +"""Stable backend discovery and metadata-only resolution; no execution imports.""" + +from collections.abc import Iterable, Mapping +from types import MappingProxyType + +from .contracts import BackendDescriptor, _capability_set + +_KNOWN_CAPABILITIES = frozenset({"causal_forward", "autoregressive_generate"}) + +# No mutable reference to the underlying registry is exposed. Dict insertion +# order is the public discovery order for contract version 1. +_BACKENDS: Mapping[str, BackendDescriptor] = MappingProxyType( + { + "local_ar": BackendDescriptor("local_ar", capabilities=frozenset({"causal_forward"})), + "hf_ar": BackendDescriptor("hf_ar", capabilities=_KNOWN_CAPABILITIES), + "u2_reference": BackendDescriptor("u2_reference", status="planned"), + "u2_native": BackendDescriptor("u2_native", status="planned"), + } +) + + +def list_backends() -> tuple[str, ...]: + """Return all builtin names in stable order, including planned backends.""" + return tuple(_BACKENDS) + + +def describe_backend(name: str) -> BackendDescriptor: + """Return immutable metadata for an exact builtin name, even when planned. + + Raises ValueError for malformed or unknown names. No model is loaded. + """ + if not isinstance(name, str) or not name: + raise ValueError("backend name must be a nonempty string") + if name not in _BACKENDS: + raise ValueError(f"Unknown backend {name!r}; available backends: {', '.join(_BACKENDS)}") + return _BACKENDS[name] + + +def resolve_backend( + *, + backend: str | None = None, + llm_backbone_id: str | None = None, + contract_version: int = 1, + required_capabilities: Iterable[str] = (), +) -> BackendDescriptor: + """Validate selectors and return metadata for an existing backend. + + With no explicit backend, a nonempty ``llm_backbone_id`` selects ``hf_ar``; + None or an empty string selects ``local_ar``. Explicit selectors must agree + with that rule. The legacy weight-initialization field ``hf_model_id`` is + intentionally not a selector or argument here. + + Only integer contract version 1 is supported. Requested capabilities must + be an iterable of known names (not a bare string or mapping). Invalid input + or an unsupported capability raises ValueError. Planned backends raise + NotImplementedError after input validation, with no fallback. + + This does not construct a model, validate a model ID against a provider, + check installed dependencies, or alter runtime routing. + """ + if type(contract_version) is not int or contract_version != 1: + raise ValueError(f"Unsupported contract_version {contract_version!r}; expected integer 1") + if llm_backbone_id is not None and not isinstance(llm_backbone_id, str): + raise ValueError("llm_backbone_id must be a string or None") + + requested = _capability_set(required_capabilities, field="required_capabilities") + unknown = requested - _KNOWN_CAPABILITIES + if unknown: + raise ValueError( + f"Unknown required_capabilities: {', '.join(sorted(unknown))}; " + f"known capabilities: {', '.join(sorted(_KNOWN_CAPABILITIES))}" + ) + + selected = backend if backend is not None else ("hf_ar" if llm_backbone_id else "local_ar") + descriptor = describe_backend(selected) + if descriptor.status == "planned": + raise NotImplementedError(f"Backend {selected!r} is planned and unavailable; no fallback") + if selected == "hf_ar" and not llm_backbone_id: + raise ValueError("backend 'hf_ar' requires a nonempty llm_backbone_id") + if selected == "local_ar" and llm_backbone_id: + raise ValueError( + "backend 'local_ar' conflicts with a nonempty llm_backbone_id (selects 'hf_ar')" + ) + + unsupported = requested - descriptor.capabilities + if unsupported: + raise ValueError( + f"Backend {selected!r} does not support required_capabilities: " + f"{', '.join(sorted(unsupported))}" + ) + return descriptor diff --git a/src/backends/contracts.py b/src/backends/contracts.py new file mode 100644 index 0000000..4e0eaae --- /dev/null +++ b/src/backends/contracts.py @@ -0,0 +1,43 @@ +"""Immutable, dependency-free metadata for the backend discovery contract.""" + +from collections.abc import Iterable, Mapping +from dataclasses import dataclass +from typing import Literal + + +def _capability_set(values: Iterable[str], *, field: str) -> frozenset[str]: + """Copy an iterable of capability names without coercing malformed inputs.""" + if isinstance(values, str | bytes | bytearray | Mapping): + raise ValueError( + f"{field} must be an iterable of capability names, not a string or mapping" + ) + try: + items = iter(values) + except TypeError as exc: + raise ValueError(f"{field} must be an iterable of capability names") from exc + names = set() + for item in items: + if not isinstance(item, str) or not item: + raise ValueError(f"{field} must contain nonempty strings; got {item!r}") + names.add(item) + return frozenset(names) + + +@dataclass(frozen=True, slots=True) +class BackendDescriptor: + """Backend metadata, never a model or a guarantee that assets are available. + + ``capabilities`` is copied to a frozenset to prevent caller-owned mutable + collections from changing a descriptor. ``status`` distinguishes current + execution paths from reserved, unavailable backend names. + """ + + name: str + contract_version: int = 1 + capabilities: frozenset[str] = frozenset() + status: Literal["existing", "planned"] = "existing" + + def __post_init__(self) -> None: + object.__setattr__( + self, "capabilities", _capability_set(self.capabilities, field="capabilities") + ) diff --git a/tests/test_backend_contract.py b/tests/test_backend_contract.py new file mode 100644 index 0000000..9e0232b --- /dev/null +++ b/tests/test_backend_contract.py @@ -0,0 +1,301 @@ +"""Standard-library checks for backend metadata without constructing models.""" + +import dataclasses +import json +import subprocess +import sys +import tempfile +import textwrap +import unittest +from pathlib import Path + +from src.backends import BackendDescriptor, describe_backend, list_backends, resolve_backend +from src.backends.capabilities import _BACKENDS + + +class BackendContractTests(unittest.TestCase): + """Check the version 1 metadata and selection boundary.""" + + def test_discovery_order_and_metadata(self): + names = ("local_ar", "hf_ar", "u2_reference", "u2_native") + self.assertIsInstance(list_backends(), tuple) + self.assertEqual(list_backends(), names) + self.assertEqual(list_backends(), names) + expected = ( + ("existing", frozenset({"causal_forward"})), + ("existing", frozenset({"causal_forward", "autoregressive_generate"})), + ("planned", frozenset()), + ("planned", frozenset()), + ) + for name, (status, capabilities) in zip(names, expected, strict=True): + with self.subTest(name=name): + descriptor = describe_backend(name) + self.assertIsInstance(descriptor, BackendDescriptor) + self.assertEqual(descriptor.name, name) + self.assertEqual(descriptor.contract_version, 1) + self.assertIs(type(descriptor.contract_version), int) + self.assertEqual(descriptor.status, status) + self.assertEqual(descriptor.capabilities, capabilities) + self.assertIsInstance(descriptor.capabilities, frozenset) + + def test_descriptors_and_registry_are_immutable(self): + for name in list_backends(): + descriptor = describe_backend(name) + for field, value in ( + ("name", "changed"), + ("contract_version", 2), + ("capabilities", frozenset()), + ("status", "planned"), + ): + with self.subTest(name=name, field=field): + with self.assertRaises(dataclasses.FrozenInstanceError): + setattr(descriptor, field, value) + with self.assertRaises(dataclasses.FrozenInstanceError): + del descriptor.name + with self.assertRaises(AttributeError): + descriptor.capabilities.add("training") + with self.assertRaises(TypeError): + _BACKENDS["local_ar"] = describe_backend("hf_ar") + with self.assertRaises(TypeError): + del _BACKENDS["u2_native"] + self.assertEqual(describe_backend("local_ar").capabilities, frozenset({"causal_forward"})) + + def test_descriptor_copies_caller_owned_capabilities(self): + names = {"causal_forward"} + descriptor = BackendDescriptor("custom", capabilities=names) + names.add("autoregressive_generate") + self.assertEqual(descriptor.capabilities, frozenset({"causal_forward"})) + self.assertIsInstance(descriptor.capabilities, frozenset) + self.assertIsInstance(hash(descriptor), int) + self.assertEqual(BackendDescriptor("custom").capabilities, frozenset()) + + def test_default_selection_matches_backbone_truthiness(self): + self.assertEqual(resolve_backend().name, "local_ar") + for backbone_id, expected in ( + (None, "local_ar"), + ("", "local_ar"), + ("example/model", "hf_ar"), + (" ", "hf_ar"), + ): + with self.subTest(backbone_id=backbone_id): + result = resolve_backend(llm_backbone_id=backbone_id) + self.assertEqual(result, describe_backend(expected)) + + def test_explicit_selection(self): + for backbone_id in (None, ""): + self.assertEqual( + resolve_backend(backend="local_ar", llm_backbone_id=backbone_id).name, + "local_ar", + ) + self.assertEqual( + resolve_backend(backend="hf_ar", llm_backbone_id="example/model").name, "hf_ar" + ) + + def test_legacy_presets_do_not_select_hf(self): + # Exercise actual presets without importing the model or optional stacks. + from src.config import ModelConfig + + for preset in ( + "prism-nano", + "prism-micro", + "prism-small", + "prism-granite-2b", + "prism-phi4-mini", + ): + with self.subTest(preset=preset): + config = ModelConfig.from_preset(preset) + self.assertTrue(config.hf_model_id) + self.assertIsNone(config.llm_backbone_id) + self.assertEqual( + resolve_backend(llm_backbone_id=config.llm_backbone_id).name, "local_ar" + ) + config = ModelConfig.from_preset("prism-olmo3-7b") + self.assertEqual(resolve_backend(llm_backbone_id=config.llm_backbone_id).name, "hf_ar") + + def test_hf_model_id_is_not_a_resolver_argument(self): + with self.assertRaisesRegex(TypeError, "hf_model_id"): + resolve_backend(hf_model_id="example/model") + + def test_conflicting_selectors(self): + for backbone_id in (None, ""): + with self.subTest(backbone_id=backbone_id): + with self.assertRaisesRegex(ValueError, "hf_ar.*nonempty llm_backbone_id"): + resolve_backend(backend="hf_ar", llm_backbone_id=backbone_id) + for backbone_id in ("example/model", " "): + with self.assertRaisesRegex(ValueError, "local_ar.*conflicts.*llm_backbone_id"): + resolve_backend(backend="local_ar", llm_backbone_id=backbone_id) + + def test_malformed_and_unknown_backend_selectors(self): + for name in ("", " ", "HF_AR", "missing", 0, 1, True, False, b"local_ar", [], {}): + with self.subTest(name=name): + with self.assertRaisesRegex(ValueError, "[Bb]ackend"): + describe_backend(name) + with self.assertRaisesRegex(ValueError, "[Bb]ackend"): + resolve_backend(backend=name) + with self.assertRaisesRegex(ValueError, "backend name"): + describe_backend(None) + + def test_malformed_backbone_ids(self): + for backbone_id in (0, 1, True, False, 1.0, b"example/model", [], {}, object()): + with self.subTest(backbone_id=backbone_id): + for backend in (None, *list_backends()): + with self.assertRaisesRegex(ValueError, "llm_backbone_id.*string or None"): + resolve_backend(backend=backend, llm_backbone_id=backbone_id) + + def test_version_validation(self): + self.assertEqual(resolve_backend(contract_version=1).contract_version, 1) + for version in (True, False, 0, -1, 2, 1.0, "1", None, [], {}): + with self.subTest(version=version): + for backend in (None, "u2_reference", "u2_native"): + with self.assertRaisesRegex(ValueError, "contract_version.*integer 1"): + resolve_backend(backend=backend, contract_version=version) + + def test_supported_capabilities_and_iterables(self): + for requested in ( + (), + [], + set(), + frozenset(), + ["causal_forward"], + {"causal_forward"}, + ("causal_forward", "causal_forward"), + iter(["causal_forward"]), + ): + with self.subTest(requested=requested): + self.assertEqual(resolve_backend(required_capabilities=requested).name, "local_ar") + self.assertEqual( + resolve_backend( + llm_backbone_id="example/model", + required_capabilities=("causal_forward", "autoregressive_generate"), + ).name, + "hf_ar", + ) + + def test_local_generation_is_unsupported(self): + with self.assertRaisesRegex( + ValueError, "local_ar.*does not support.*autoregressive_generate" + ): + resolve_backend(required_capabilities=["autoregressive_generate"]) + + def test_malformed_capability_inputs(self): + malformed = ( + None, + True, + 1, + "causal_forward", + b"", + bytearray(), + {}, + {"causal_forward": True}, + [None], + [1], + [True], + [""], + [[]], + [{}], + ) + for requested in malformed: + with self.subTest(requested=requested): + for backend in (None, "u2_reference", "u2_native"): + with self.assertRaisesRegex(ValueError, "required_capabilities"): + resolve_backend(backend=backend, required_capabilities=requested) + + def test_unknown_capabilities_precede_planned_rejection(self): + for capability in ( + "unknown", + "CAUSAL_FORWARD", + "image", + "structured_decoder", + "diffusion", + "training", + "xpu", + ): + for backend in (None, "hf_ar", "u2_reference", "u2_native"): + with self.subTest(backend=backend, capability=capability): + with self.assertRaisesRegex(ValueError, "Unknown required_capabilities"): + resolve_backend(backend=backend, required_capabilities=[capability]) + + def test_planned_backends_never_fall_back(self): + for backend in ("u2_reference", "u2_native"): + for backbone_id in (None, "", "example/model"): + for requested in ((), ("causal_forward",), ("autoregressive_generate",)): + with self.subTest( + backend=backend, backbone_id=backbone_id, requested=requested + ): + with self.assertRaisesRegex( + NotImplementedError, f"{backend}.*planned.*no fallback" + ): + resolve_backend( + backend=backend, + llm_backbone_id=backbone_id, + required_capabilities=requested, + ) + + def test_import_and_metadata_calls_without_site_packages_or_side_effects(self): + root = Path(__file__).resolve().parents[1] + script = textwrap.dedent("""\ + import json + import os + import sys + + assert sys.flags.no_site + sys.path.insert(0, sys.argv[1]) + violations = [] + forbidden = {"torch", "transformers", "huggingface_hub", "requests", + "src.model", "src.config", "src.train"} + + def audit(event, args): + blocked = False + if event == "import": + blocked = any(args[0] == name or args[0].startswith(name + ".") + for name in forbidden) + elif event.startswith(("socket.", "urllib.")): + blocked = True + elif event in {"subprocess.Popen", "os.system", "os.posix_spawn"}: + blocked = True + elif event == "open": + path, mode, flags = args + writes = os.O_WRONLY | os.O_RDWR | os.O_CREAT | os.O_TRUNC | os.O_APPEND + # Import machinery may read Python source/bytecode only. + blocked = bool(flags & writes) or not ( + isinstance(path, str) and path.endswith((".py", ".pyc")) + ) + if blocked: + violations.append(event) + raise AssertionError("Forbidden metadata side effect: " + event) + + sys.addaudithook(audit) + from src.backends import describe_backend, list_backends, resolve_backend + + for name in list_backends(): + describe_backend(name) + assert resolve_backend().name == "local_ar" + assert resolve_backend(llm_backbone_id="not/a/real/model").name == "hf_ar" + for name in ("u2_reference", "u2_native"): + try: + resolve_backend(backend=name) + except NotImplementedError: + pass + else: + raise AssertionError("Planned backend resolved") + assert not violations, violations + assert not any(module == name or module.startswith(name + ".") + for module in sys.modules for name in forbidden) + print(json.dumps(list_backends())) + """) + with tempfile.TemporaryDirectory() as cwd: + result = subprocess.run( + [sys.executable, "-B", "-S", "-c", script, str(root)], + cwd=cwd, + capture_output=True, + text=True, + timeout=30, + check=False, + ) + self.assertEqual(list(Path(cwd).iterdir()), []) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(json.loads(result.stdout), list(list_backends())) + + +if __name__ == "__main__": + unittest.main()