Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/api/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
6 changes: 6 additions & 0 deletions src/backends/__init__.py
Original file line number Diff line number Diff line change
@@ -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")
91 changes: 91 additions & 0 deletions src/backends/capabilities.py
Original file line number Diff line number Diff line change
@@ -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
43 changes: 43 additions & 0 deletions src/backends/contracts.py
Original file line number Diff line number Diff line change
@@ -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")
)
Loading
Loading