[Sande33p]

Description

Add dependency-free discovery and resolution metadata for PRISM's existing local and Hugging Face causal paths. Callers can enumerate backend names, inspect immutable descriptors and reject conflicting selectors or unsupported capabilities before model construction.

u2_reference and u2_native are explicitly planned and unavailable. This is the first metadata slice of the optional-backend roadmap; it does not load InternLumina-U2, add diffusion execution or wire the resolver into model construction or training.

Proposal: Sande33p#1

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update

Compatibility

• src.* import paths — adds src.backends; existing imports remain intact.

No migration is required. Default metadata resolution follows existing llm_backbone_id truthiness. Legacy hf_model_id remains an initialization field. Existing CLI, Hydra, ModelConfig, checkpoints, launchers and runtime selection are unchanged.

How Has This Been Tested?

At commit a7c7552a9c626a0170b98ed381e15757a1e111d7:

python -B -m unittest discover -s tests -p test_backend_contract.py -v
python -B -m pytest -q -p no:cacheprovider tests/multimodal/test_modality_config_typed.py
python -B -m ruff check src/backends tests/test_backend_contract.py
python -B -m ruff format --check src/backends tests/test_backend_contract.py
python -B -m mypy src/backends
git diff --check

• 17 backend tests pass on Python 3.10.19 and 3.13; five existing typed-config tests pass on 3.10.19.
• Ruff lint/format, Mypy for the three source files and whitespace checks pass.
• The backend suite launches python -B -S from an empty temporary directory and rejects optional-model imports, asset reads, writes, process launches and network activity while exercising metadata operations.
• All nine required GitHub CI checks passed at this head: lint, doc_links, both Python 3.10/3.12 type and unit jobs, multimodal_contract, launcher_contract and coverage_gate.
• Platform: local macOS, CPU only, plus the repository CI environments. No new dependencies or assets.
• Broad model/training, accelerator and Aurora tests were not run: this slice changes only standard-library metadata and API documentation. Python 3.12 results come from the passing GitHub jobs, not from inference based on the local Python 3.13 results.

New Dependencies, Data, or Assets

None.

Checklist

• Automated author/operator self-review completed
• Changed files pass Ruff and Mypy checks
• Code intent is documented where needed
• API documentation updated
• Focused new and relevant existing tests pass locally
• No secrets, credentials, absolute institutional paths, weights or data included
• Required repository CI and accountable human review completed

AI/LLM Assistance

• AI/LLM tools were primarily used to generate code or artifacts in this PR
• A human has reviewed all such output line-by-line and understands it

The native Paperclip Modality Integration worker generated the implementation and CPU tests. Its Git staging operation was denied by the sandbox and its run timed out. The operator preserved the work, corrected lint/formatting, reran validation and created the commit. This is an operator-assisted contribution; the author run is not represented as successful or autonomous. Native Evaluation independently approved this exact commit after reviewing a clean Git archive and rerunning the focused checks. It does not substitute for accountable human review.

Additional Context

Plan and operating boundaries: https://github.com/Sande33p/PRISMAgents/pull/4

The advertised capabilities are conservative: local causal_forward; HF causal_forward and autoregressive_generate. No diffusion, modality, training, structured-decoder, quality or XPU capability is asserted. The existing local generate() placeholder is deliberately not advertised.

[Copilot]

🟢 Approval recommended

No active review issues remain for the backend metadata contract changes.

No open issues 🎉

What changed in this PR

Adds a dependency-free backend metadata contract so callers can discover existing execution paths and validate selectors and capabilities before model construction. Runtime routing remains unchanged, and U2 backends are explicitly planned and unavailable.

Changes:

• Introduces immutable backend descriptors and stable discovery and resolution APIs.
• Validates selector conflicts, contract versions, and capability requests without loading models.
• Adds contract tests and documentation covering compatibility and side-effect-free metadata operations.

File	Description
tests/​test_backend_contract.py	Tests discovery, immutability, validation, legacy selection, and side-effect isolation.
src/​backends/​contracts.py	Defines immutable descriptors and capability normalization.
src/​backends/​capabilities.py	Implements the registry, discovery, and metadata-only resolution.
src/​backends/​__init__.py	Exports the public backend metadata API.
docs/​api/​model.md	Documents version 1 capabilities, selection rules, and execution boundaries.

_{Review effort: Balanced}