phenotypic.sdk_.typing_ module

class phenotypic.sdk_.typing_.TuneSpec(low: float | None = None, high: float | None = None, *, step: float | None = None, log: bool = False, categories: tuple | None = None, tunable: bool = True)

Bases: object

Per-field tuning-search metadata (Tier-1 inference override).

TuneSpec mirrors the existing field-marker pattern (_ColumnRefMarker, _OperationFieldMarker): a frozen, slotted, non-pydantic sentinel that is a complete no-op at runtime and is read only by infer_search_space, via op.model_fields[name].metadata (where pydantic v2 stores Annotated extras). It rides in an Annotated[T, TuneSpec(...)] chain:

class GaussianBlur(ImageEnhancer):
    sigma:    Annotated[float, TuneSpec(0.5, 5.0, log=True)] = 2.0
    truncate: Annotated[float, TuneSpec(tunable=False)]      = 4.0

At runtime sigma is still a plain float; GaussianBlur(sigma=999.0) constructs exactly as before. The marker is the search domain, never the valid domain — validity stays the job of pydantic Field(ge=, le=).

It lives here (not in phenotypic.tune) so operation modules can import it without dragging in the tune engine — the public re-export from phenotypic.tune import TuneSpec still works.

Parameters:

• low (float | None) – Inclusive lower search bound (positional). None leaves the bound to Tier-2 inference / the co-located Field constraint.

• high (float | None) – Inclusive upper search bound (positional). None as low.

• step (float | None) – Discretization stride — integer step or quantized float. None means continuous (or unit-step for integers).

• log (bool) – Whether to sample on a logarithmic scale (default False).

• categories (tuple | None) – Override / subset the auto-derived categorical choices. A list is coerced to a tuple so the marker stays hashable.

• tunable (bool) – False excludes the field from tuning outright and short-circuits Tier-2 (default True).

Note

This is not a pydantic model — it is a plain slotted sentinel so it can sit in an Annotated chain without pydantic trying to validate it. It carries __eq__/__hash__ over the full field tuple so a duplicate in an Annotated chain de-dupes (PEP 593 chain semantics).

categories: tuple | None

high: float | None

log: bool

low: float | None

step: float | None

tunable: bool

phenotypic.sdk_.typing_.polymorphic_field(base: type | Callable[[], type], *, marker: Any = None)

A pydantic field for a polymorphic model subtree.

The concrete subclass survives a JSON round-trip via the phenotypic class registry: the field serializes to {"class": <name>, "params": {...}} (or the pipeline-tagged form for an ImagePipeline) and reconstructs the concrete subclass on load.

Parameters:

• base (type | Callable[[], type]) – Constrains the accepted/validated type — a class or a zero-arg callable returning the class (the lazy form avoids import cycles, e.g. OperationField naming BaseOperation).

• marker (Any) – Optional sentinel attached to the Annotated chain (e.g. the GUI’s _OperationFieldMarker) so introspecting tools can recognise the field despite the Any core erasure.

Returns:

An Annotated type usable as a pydantic field annotation. Host models must set model_config with arbitrary_types_allowed=True.

phenotypic.sdk_.typing_.CheckpointType

--checkpoint-type flag values for the SLURM sentinel handler.

alias of Literal[‘manifest’, ‘finalize’]

phenotypic.sdk_.typing_.CliMode

Public top-level CLI execution mode. full performs the normal apply-and-measure run, measure reruns measurement from existing HDFs, recompile refreshes aggregate outputs from an existing output root, and process performs the apply-only single-layer export selected by --layer.

alias of Literal[‘full’, ‘measure’, ‘recompile’, ‘process’]

phenotypic.sdk_.typing_.CompositeBlend

The single-objective composite blend selector — the serialized value of CompositeScorer.blend. "tchebycheff" (default) is conjunctive (worst-axis-dominant, augmented Tchebycheff over per-child cost); "weighted_mean" is the compensatory opt-out. No Enum partner is needed — this is a serialized field value with no separate documentation surface (mirrors DetectMode / ExecutionMode). The geometric-mean-of-cost blend is intentionally NOT offered (it inverts the conjunctive property).

alias of Literal[‘tchebycheff’, ‘weighted_mean’]

phenotypic.sdk_.typing_.DinoSize

DINO backbone size for DinoSam2Detector. Maps with DinoVersion to the HF model id (e.g. (2, “base”) -> “facebook/dinov2-base”).

alias of Literal[‘small’, ‘base’, ‘large’]

phenotypic.sdk_.typing_.DinoVersion

DINO backbone generation for DinoSam2Detector. 2 = DINOv2 (Apache, ungated, default); 3 = DINOv3 (gated, opt-in — routes through require_license_acceptance). Type-only closed set (no Enum / documentation surface needed).

alias of Literal[2, 3]

phenotypic.sdk_.typing_.ExecutionMode

Forward-run / recompile execution backend. Bare-string carrier for serialization (progress/job_metadata.json); callers convert to/from the dataclass field of the same name on ProcessingState / ExecutionResults.

alias of Literal[‘local’, ‘slurm’]

phenotypic.sdk_.typing_.FailureSource

Tag attached to each row of progress/failures.jsonl distinguishing Python-side exceptions from SLURM sbatch failures.

alias of Literal[‘python’, ‘slurm’]

phenotypic.sdk_.typing_.GpuInputLayer

Image layer a GpuDetector consumes as model input. Single-channel layers (gray/detect_mat) are stacked to (H, W, 3) by GpuDetector.preprocess.

alias of Literal[‘rgb’, ‘gray’, ‘detect_mat’]

phenotypic.sdk_.typing_.GpuOutputKind

Object output a GpuDetector produces. “instance” -> labeled objmap; “semantic” -> binary objmask (auto-labels into objmap, like a threshold detector).

alias of Literal[‘instance’, ‘semantic’]

phenotypic.sdk_.typing_.ImageTypeName

String form of the IMAGE_TYPES Enum’s BASE and GRID members, which are the only two image-type values that cross CLI / GUI boundary code today. Other IMAGE_TYPES members (CROP / OBJECT / GRID_SECTION) are internal to the core library and don’t need a Literal partner yet.

alias of Literal[‘Image’, ‘GridImage’]

phenotypic.sdk_.typing_.NdArrayField

Annotated np.ndarray usable as a pydantic field annotation.

Accepts a list / nested list or an np.ndarray as input, serializes to a JSON-native nested list, and reports an "array" JSON schema. The host model must declare model_config with arbitrary_types_allowed=True (the field type is the arbitrary, non-pydantic np.ndarray).

Example

>>> import numpy as np
>>> from pydantic import BaseModel, ConfigDict
>>> from phenotypic.sdk\_.typing_ import NdArrayField
>>> class KernelOp(BaseModel):
...     model_config = ConfigDict(arbitrary_types_allowed=True)
...     kernel: NdArrayField
>>> op = KernelOp(kernel=[[1, 0], [0, 1]])
>>> isinstance(op.kernel, np.ndarray)
True
>>> op.model_dump(mode="json")["kernel"]
[[1, 0], [0, 1]]
>>> KernelOp.model_json_schema()["properties"]["kernel"]["type"]
'array'

alias of Annotated[ndarray, BeforeValidator(func=_coerce_to_ndarray, json_schema_input_type=PydanticUndefined), PlainSerializer(func=_ndarray_to_list, return_type=list, when_used=always), WithJsonSchema(json_schema={‘items’: {}, ‘type’: ‘array’}, mode=None)]

phenotypic.sdk_.typing_.OperationField

Annotated operation type usable as a pydantic field annotation for a parameter that holds another operation or a nested pipeline.

Back-compat alias — an operation/pipeline-valued field built by polymorphic_field(). Serializes to a class-tagged dict so the concrete subclass survives a JSON round-trip; deserializes by resolving the class through the phenotypic registry. Use it directly (OperationField) or inside a container — e.g. list[OperationField] — when the field must accept several operation types and round-trip each losslessly.

The core type is Any (naming the operation base classes here would create an import cycle through sdk_); an AfterValidator restores the operation/pipeline type guard. The trailing _OperationFieldMarker lets the GUI OperationRegistry recognise the field despite the Any erasure.

alias of Annotated[Any, BeforeValidator(func=_deserialize_operation_value, json_schema_input_type=PydanticUndefined), AfterValidator(func=_require), PlainSerializer(func=_serialize_operation_value, return_type=PydanticUndefined, when_used=always), _OperationFieldMarker()]

phenotypic.sdk_.typing_.ProcessOnlyLayer

Image layer a process-mode CLI run exports. A closed subset of the layers exposed as Image accessors; rgb/gray/ detect_mat save as TIFF, objmap as a raw-label PNG.

alias of Literal[‘rgb’, ‘gray’, ‘detect_mat’, ‘objmap’]

phenotypic.sdk_.typing_.ProcessingStatus

Per-image processing-events log statuses. Used by _cli_update_state and consumed by the dashboard generator.

alias of Literal[‘started’, ‘completed’, ‘failed’]

phenotypic.sdk_.typing_.RecompileTaskType

--recompile-task flag values for the SLURM recompile worker. Mirrors the bare-string TASK_* constants in _cli_recompile_slurm_scripts.py.

alias of Literal[‘measurements’, ‘overlay’, ‘finalize’]