Source code for phenotypic.abc_._requirements
"""What an operation needs from its run, stated by the operation itself.
Spec: ``docs/superpowers/specs/2026-09-24-cli-preflight/design.md`` §3.
The CLI's run preflight reads these declarations to refuse an incompatible
run before any image is processed: a grid operation under ``--image-type
Image``, an RGB-reading operation on grayscale inputs, a detector whose
optional package or model weights are missing. Declaring them on the
operation, beside the code that creates the requirement, keeps them from
drifting the way a checker-side table would as operations are added.
Standard library only: this module is imported by ``phenotypic.abc_`` and must
not add to its import cost.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Callable, Optional
[docs]
@dataclass(frozen=True)
class WeightRequirement:
"""Model weights an operation loads at run time.
Attributes:
model: A readable identifier, e.g. ``"sam2:tiny"`` or ``"dinov3:base"``.
license_key: The ``PHENOTYPIC_ACCEPT_MODEL_LICENSE`` token that must be
accepted before the weights may be downloaded or used, or ``None``
when the weights are not gated.
is_cached: Reports whether the weights are already on local disk,
without importing ``torch`` and without network access. Returns
``None`` when that cannot be told.
"""
model: str
license_key: Optional[str]
is_cached: Callable[[], Optional[bool]]
[docs]
@dataclass(frozen=True)
class OperationRequirements:
"""Everything an operation needs from the run that executes it.
Attributes:
grid_image: The operation raises ``GridImageInputError`` on a plain
``Image``.
rgb_input: The operation reads RGB pixels and fails on a grayscale
image.
modules: Importable module names the operation imports lazily; checked
with ``importlib.util.find_spec``, never imported.
extra: The ``pyproject`` extra that provides ``modules``, named in the
remedy; ``None`` when no extra does (e.g. a conda-only package).
weights: Model weights the operation loads.
"""
grid_image: bool = False
rgb_input: bool = False
modules: tuple[str, ...] = ()
extra: Optional[str] = None
weights: tuple[WeightRequirement, ...] = ()