Models and plans¶
altar.models is what a model binding imports: manifests, configuration and run-input bases, resource and
credential references, saved configurations, plan serializers, ModelPlugin, and logical path layouts. Importing
it loads no model SDK, storage adapter or execution backend.
Stable. A few names and hooks are provisional; Provisional names lists them.
models
¶
Stable model-binding contracts.
External model bindings should import from this module. Names re-exported here are covered by Altar's
public compatibility policy; their original altar.plugins.model locations are implementation paths.
DEFAULT_GENOME_BUILD
module-attribute
¶
The variant assembly a caller gets when it does not name one.
GENOME_BUILD_ALIASES
module-attribute
¶
GENOME_BUILD_ALIASES: Mapping[str, tuple[str, ...]] = (
MappingProxyType(
{
"hg19": ("GRCh37",),
"hg38": ("GRCh38",),
"mm10": ("GRCm38",),
"mm39": ("GRCm39",),
}
)
)
The assemblies Altar knows, each canonical label mapped to the other spellings it accepts.
VARIANT_ROW_PLACEHOLDER
module-attribute
¶
The placeholder a variant-scoped artifact's logical path pattern carries for a variant's batch row.
DigestMismatchError
¶
Bases: ValueError
A path does not hold the single regular file whose bytes a digest names.
VariantIdentityError
¶
Bases: ValueError
A variant key is malformed, non-canonical, or disagrees with its locus.
VariantKey
dataclass
¶
Canonical one-based biallelic key serialized as chr:pos:ref:alt.
Fields follow the rules in this module's documentation. The class normalizes spelling but does not normalize biological representation. Callers must left-align and trim indels against the selected reference before constructing a key when equivalence across representations matters.
parse
classmethod
¶
parse(variant_id: str) -> VariantKey
Parse and normalize a four-field textual key.
require_canonical
classmethod
¶
require_canonical(variant_id: str) -> VariantKey
Parse variant_id and reject aliases instead of silently rewriting them.
from_fields
classmethod
¶
from_fields(
chromosome: str,
position: int,
reference_allele: str,
alternate_allele: str,
) -> VariantKey
Construct a canonical key from decomposed one-based locus fields.
CapabilityNotSupported
¶
Bases: NotImplementedError
Raised by an optional plugin method that the adapter deliberately does not implement.
It subclasses NotImplementedError, so an existing except NotImplementedError still catches it. It is a
named, catchable signal distinct from a genuinely missing abstract method: a caller probing an optional
capability can except CapabilityNotSupported without also swallowing real not-yet-implemented bugs.
UnknownGenomeBuildError
¶
Bases: ValueError
Raised when a genome build label names no assembly Altar knows.
LineageDescriptor
dataclass
¶
LineageDescriptor(
plugin_id: str,
plugin_kind: PluginKind,
architecture: str | None,
plugin_version: str,
runtimes: tuple[RuntimeIdentity, ...],
reducer: str | None,
output_selection_hash: str,
genome_build: str,
genome_hash: str | None,
schema_hash: str,
configuration: dict[str, Any],
schema_name: str = "primary",
format: int = LINEAGE_DESCRIPTOR_FORMAT,
)
The unhashed inputs of one generated score-lineage ID.
configuration is the binding's frozen scientific_dict() projection exactly as
ModelPlugin.scoring_run_identity hashes it, wrapped as {"model_configuration": ..., "genome": ...}
when the run has a structured genome. It holds no locations or credentials, because the projection drops
them. Build one with ModelPlugin.scoring_lineage_descriptor or scoring_lineage_descriptor_for; a
stored one round-trips through :meth:to_json and :meth:from_json.
configuration_hash
¶
Return the hash of configuration: the run identity's scientific_configuration_hash.
verify
¶
verify(identity: PluginRunIdentity) -> None
Raise IncompatibleResultError unless this descriptor is the one behind identity.
The configuration must hash to the identity's scientific_configuration_hash and every other field
must reproduce the identity's generated lineage ID.
from_dict
classmethod
¶
from_dict(data: Mapping[str, Any]) -> LineageDescriptor
Rebuild a descriptor, rejecting missing or unknown fields.
from_json
classmethod
¶
from_json(value: str) -> LineageDescriptor
Rebuild a descriptor from :meth:to_json output.
AnnotationDependency
dataclass
¶
An annotation contract required by the prioritization policy.
ApiVersionRange
dataclass
¶
A half-open Altar API interval: minimum <= version < maximum.
ArtifactSchema
dataclass
¶
ArtifactSchema(
name: str,
version: str,
description: str,
media_type: str,
scope: ArtifactScope = BATCH,
)
One versioned, named opaque result file owned by a model binding.
An artifact carries rich output that is neither a scalar row nor a row-shaped table: a prediction matrix,
per-bin tracks, a profile, an interpretation product. Altar never decodes it. The engine verifies that the
file exists, computes its content digest, and hands it to an :class:~altar.results.ArtifactStore with
the identity of the task that produced it and the variants it covers. media_type is an IANA-style
type/subtype string (application/x-npz, application/vnd.apache.parquet, image/png) that
tells a consumer how to open the bytes; scope says what one file covers.
An artifact is produced only when a run's :class:~altar.models.OutputSelection names it in outputs,
so declaring one changes no existing run's identity or cache.
schema_hash
property
¶
Hash what decides how stored bytes are interpreted: the name, media type, and scope.
ArtifactScope
¶
Bases: StrEnum
What one stored artifact file covers.
BATCH is one file per scoring task, covering every variant of that task's batch (a prediction matrix
with one row per variant). VARIANT is one file per variant of the batch (a per-variant attribution or
track file): its record covers exactly that variant and its :class:~altar.results.ArtifactKey names it.
A container plan declares a variant-scoped artifact as one output whose logical path is a
:meth:~altar.models.ScoringLayout.artifact_variant_result_pattern, which
:func:~altar.scoring.executable_scoring_plan turns into one collected file per variant. Inline plans
cannot produce a VARIANT artifact yet; selecting one is rejected before compute.
DetailSchema
dataclass
¶
DetailSchema(
name: str,
version: str,
description: str,
fields: tuple[ResultField, ...],
key_fields: tuple[str, ...],
row_count_field: str | None = None,
)
One versioned, named one-to-many result table owned by a model binding.
variant_id is the implicit parent key and must not be repeated in fields. key_fields names
the binding-declared fields that, together with variant_id, identify one logical detail row. Key
values may be null when the upstream science has no value (for example a non-gene-centric track has no
gene ID); stores use Altar's canonical logical-key encoding rather than backend-specific NULL equality.
row_count_field optionally names an int field of the plugin's primary result schema that holds
the number of rows a variant has in this table. It is a completion signal, not science: cache-miss
preparation treats a cached primary row whose value is 0 as complete for the table (the variant
legitimately produced no rows) instead of a conservative miss, and the scoring engine rejects a run whose
routed rows per variant disagree with the field. It does not enter :attr:schema_hash, so declaring it
changes no stored table's identity.
schema_hash
property
¶
Hash row identity and biological meaning, excluding descriptions and display labels.
IncompatibleAltarApiError
¶
Bases: ManifestError
Raised when a plugin does not support the running Altar API.
IncompatibleResultError
¶
Bases: ManifestError
Raised before results are decoded with an incompatible plugin contract.
IneligibilityReason
¶
Bases: StrEnum
Why a variant is set aside before scoring.
The first two reasons are the manifest's, from :meth:VariantEligibility.ineligibility. The others are
found by batch preparation when it checks the admitted candidates against the reference genome and the
allele normalization ingestion applies; a model never declares them.
UNSUPPORTED_VARIANT_CLASS
class-attribute
instance-attribute
¶
The variant's :class:VariantClass is not among the manifest's variant_classes.
ALLELE_TOO_LONG
class-attribute
instance-attribute
¶
REF or ALT is longer than the manifest's max_allele_length.
CONTIG_MISSING
class-attribute
instance-attribute
¶
The reference FASTA has no contig under the variant's canonical chromosome name.
REFERENCE_MISMATCH
class-attribute
instance-attribute
¶
REF is not the reference sequence at the variant's position, or runs past the end of the contig.
NOT_NORMALIZED
class-attribute
instance-attribute
¶
The alleles are not minimal or, when checked against a reference, not left-aligned, so the key names the variant differently from ingestion and the annotation lookups.
ManifestError
¶
Bases: ValueError
Base class for invalid or incompatible plugin ABI data.
PluginCapability
¶
Bases: StrEnum
An operation a plugin declares it performs: scoring, interpretation, preprocessing or result assembly.
PluginKind
¶
Bases: StrEnum
The kind of extension a plugin manifest describes, such as a model or an annotation source.
PluginManifest
dataclass
¶
PluginManifest(
plugin_id: str,
kind: PluginKind,
capabilities: frozenset[PluginCapability],
architecture: str | None,
plugin_version: str,
altar_api: ApiVersionRange,
configuration_schema_version: str,
result_schema: ResultSchema,
prioritization: PrioritizationPolicy,
runtimes: tuple[RuntimeRequirement, ...],
detail_schemas: tuple[DetailSchema, ...] = (),
variant_eligibility: VariantEligibility = VariantEligibility(),
manifest_schema_version: str = MANIFEST_SCHEMA_VERSION,
artifact_schemas: tuple[ArtifactSchema, ...] = (),
)
The immutable declaration shipped by one plugin release.
detail_schema
¶
detail_schema(name: str) -> DetailSchema
Return one declared detail schema by name or fail with the available names.
artifact_schema
¶
artifact_schema(name: str) -> ArtifactSchema
Return one declared artifact schema by name or fail with the available names.
selected_artifact_schemas
¶
selected_artifact_schemas(
outputs: Sequence[str],
) -> tuple[ArtifactSchema, ...]
Return the declared artifacts a run produces: those an output selection names, in manifest order.
Unlike detail tables, which every run of a binding produces, an artifact is opt-in through
:attr:~altar.models.OutputSelection.outputs. Names in outputs that are not artifacts ("scores",
a detail name, a binding-defined output) are the binding's to validate and are ignored here.
PluginRunIdentity
dataclass
¶
PluginRunIdentity(
plugin_id: str,
plugin_kind: PluginKind,
architecture: str | None,
plugin_version: str,
supported_altar_api: ApiVersionRange,
altar_api_version: str,
result_schema_hash: str,
runtimes: tuple[RuntimeIdentity, ...],
reducer: str | None = None,
configuration_hash: str | None = None,
output_selection_hash: str | None = None,
genome_build: str | None = None,
scientific_configuration_hash: str | None = None,
genome_hash: str | None = None,
)
Transport-safe exact identity attached to a run and its result set.
The optional scoring-context fields distinguish concrete model instances, not merely wrapper ABIs.
configuration_hash preserves the complete durable configuration for exact provenance, while
scientific_configuration_hash may omit typed operational credentials for cache compatibility.
genome_hash records the structured genome's scientific projection separately so an engine can verify
that a plan was built from the request it is about to execute. These fields are optional when inspecting
a plugin before configuring a concrete model, but persistence requires :meth:assert_scoring_context.
Prioritization, annotation dependencies, schema release labels, and the full manifest hash deliberately
stay out of this identity: changing downstream selection must not invalidate raw scores.
assert_altar_compatible
¶
Reject executing this recorded plan under an API its wrapper did not support.
assert_scoring_context
¶
Reject unconfigured identities that do not identify weights, outputs, and genome.
primary_result_compatibility
¶
primary_result_compatibility() -> ResultCompatibility
Return the scientific cache identity for the primary scalar score table.
scientific_dict
¶
Return the projection that keys and defines a generated score lineage.
A lineage identifies what can change a primary score: the plugin release and its exact runtimes,
the scientific configuration projection, the output selection, the genome build and the genome's
scientific hash, and the primary result schema. The exact configuration_hash stays out
because it also covers resource locations and every declared serialization detail, so a schema
migration that adds defaulted fields, or unchanged bytes served from a new location, would
otherwise orphan every cached score. The framework API versions stay out for the same reason.
Two runs whose projections are equal share one lineage ID, and a lineage store accepts either run
for that lineage (ScoreLineage.same_lineage), so each reuses the other's scores. Exact provenance
is not lost: the catalog keeps one deterministic representative identity, and each distinct exact
identity that registers to write scores under the lineage is recorded once in the store's lineage
provenance table, read back as a set with ScoreStore.read_lineage_provenance.
detail_result_compatibility
¶
detail_result_compatibility(
schema: DetailSchema,
) -> ResultCompatibility
Return the scientific cache identity for one named detail result table.
artifact_result_compatibility
¶
artifact_result_compatibility(
schema: ArtifactSchema,
) -> ResultCompatibility
Return the scientific cache identity for one named artifact output.
PrioritizationPolicy
dataclass
¶
PrioritizationPolicy(
name: str,
version: str,
annotation_dependencies: tuple[
AnnotationDependency, ...
] = (),
)
The name and version of a binding's default prioritization rule, and the annotation columns it reads.
ResultCompatibility
dataclass
¶
ResultCompatibility(
role: ResultRole,
plugin_id: str,
plugin_kind: PluginKind,
architecture: str | None,
plugin_version: str,
runtimes: tuple[RuntimeIdentity, ...],
reducer: str | None,
configuration_hash: str,
output_selection_hash: str,
genome_build: str,
schema_name: str,
schema_hash: str,
)
Role-specific scientific identity used to decide whether persisted results may be reused.
Plugin releases and exact runtimes distinguish computations. Reusing a previous release requires an explicit score-lineage acceptance; version numbers alone never establish scientific equivalence. Framework compatibility and display metadata are not scientific cache gates. Prioritization is not part of score identity at all.
fingerprint
property
¶
Return the canonical role-specific compatibility fingerprint.
ResultField
dataclass
¶
ResultField(
name: str,
dtype: Literal["float", "bool", "int", "str"],
label: str,
meaning: str,
nullable: bool = True,
)
One ordered scalar result field, including its durable biological meaning.
ResultRole
¶
Bases: StrEnum
The persisted result role whose compatibility is being evaluated.
ResultSchema
dataclass
¶
ResultSchema(version: str, fields: tuple[ResultField, ...])
A versioned ordered schema with a biological-compatibility hash.
The complete schema, including display labels and its version, remains in the manifest for provenance.
schema_hash deliberately covers only fields that change how stored values are interpreted.
schema_hash
property
¶
Hash ordered storage and biological meaning, excluding presentation labels.
RuntimeIdentity
dataclass
¶
RuntimeIdentity(
name: str, kind: RuntimeKind, identity: str
)
The runtime one computation used, such as an image digest, under the name of the requirement it meets.
RuntimeIdentityError
¶
Bases: ManifestError
Raised when a run does not satisfy its manifest's runtime identity policy.
RuntimeIdentityPolicy
¶
Bases: StrEnum
How an actual runtime value is checked and recorded for a run.
RuntimeKind
¶
Bases: StrEnum
What a runtime requirement names: a container image, an external service, or code in the calling process.
RuntimeRequirement
dataclass
¶
RuntimeRequirement(
name: str,
kind: RuntimeKind,
policy: RuntimeIdentityPolicy,
declared_identity: str | None = None,
)
One named runtime role and the policy for its per-run identity.
VariantClass
¶
Bases: StrEnum
The allele-length class of one canonical biallelic variant.
Classification compares REF and ALT lengths exactly as written. It does not trim shared bases or
left-align, so both an anchored VCF insertion (A>AT) and a delins that lengthens the sequence
(A>GT) are insertions: a sequence model substitutes the whole ALT for the whole REF either way.
SNV
class-attribute
instance-attribute
¶
One reference base replaced by one different base.
VariantEligibility
dataclass
¶
VariantEligibility(
variant_classes: frozenset[VariantClass] = (
lambda: frozenset(VariantClass)
)(),
max_allele_length: int | None = None,
)
The variants a model can score, declared once in its manifest.
variant_classes lists the admitted :class:VariantClass values. max_allele_length, when set,
bounds the longer of REF and ALT in bases. The default admits every class at any length, which is
how a manifest that declares nothing behaves. Batch preparation excludes and reports ineligible
variants before cache lookup, and the scoring engine rejects result rows for them.
Eligibility filters inputs; it is not a score-changing setting. The score of an eligible variant does
not depend on it, so it is excluded from :class:PluginRunIdentity and score lineage.
is_unrestricted
property
¶
Whether every variant class at every allele length is eligible.
ineligibility
¶
ineligibility(
key: VariantKey,
) -> IneligibilityReason | None
Return why key is ineligible, or None when the model can score it.
Version
dataclass
¶
A deliberately small SemVer core used by the ABI (no prerelease syntax).
ConfigurationError
¶
Bases: ValueError
Base error for durable model configuration.
ConfigurationIdentityError
¶
Bases: ConfigurationError
A saved configuration belongs to a different plugin or schema.
ConfigurationManifest
dataclass
¶
ConfigurationManifest(
plugin_id: str,
plugin_version: str,
schema_id: str,
schema_version: str,
configuration_model: type[ModelConfiguration],
run_input_model: type[ModelRunInputs],
)
Plugin and schema identity attached to every saved configuration.
ConfigurationModel
¶
Bases: BaseModel
Strict, frozen, JSON-serializable base for Altar's durable public values.
Unknown fields are forbidden and defaults are validated. The wrapper methods are the supported public serialization/schema API; Pydantic remains an implementation detail behind them.
ConfigurationVersionError
¶
Bases: ConfigurationError
A saved configuration needs a migration that the plugin does not provide.
EmptyModelConfiguration
¶
LegacyArtifactError
¶
Bases: ConfigurationError
A legacy artifact mapping cannot be converted safely.
LegacyScoringConversion
dataclass
¶
LegacyScoringConversion(
configuration: ModelConfiguration,
run_inputs: ModelRunInputs,
output: OutputSelection,
runtime: RuntimeContext | None = None,
)
Explicit result of converting a supported legacy artifact mapping.
ModelConfiguration
¶
Bases: ConfigurationModel
Durable, architecture-specific model configuration.
to_dict() is the complete saved configuration. scientific_dict() is the cache-identity view:
fields typed to contain SecretReference are operational and excluded recursively, while every other
durable value remains identity-bearing.
scientific_dict
¶
Return the scientific cache-identity projection of this configuration.
A field whose annotation contains SecretReference is wholly operational. This type-driven rule
applies even when its current value is None, so adding, removing, or rotating a credential does
not change scientific identity. Nested configuration models are traversed recursively.
ModelRunInputs
¶
Bases: ConfigurationModel
Base per-run biological inputs shared by scoring plugins.
genome_build is the assembly of the run's variants. It selects the reference sequence the run reads
and is the genome build that the run's score identity and every stored score record, even when the model
was trained on another assembly (see TrainingAssemblyConfiguration). It is normalized to Altar's
spelling, so "GRCh38" is stored as "hg38" (see canonical_genome_build). genome records the
optional reference resource for that assembly, for integrations that can identify one. Models that read
local reference sequence bytes should inherit ReferenceGenomeRunInputs, which requires a content
address.
A binding that can read sequence only on particular assemblies declares them in
supported_genome_builds; any other genome_build is then rejected at validation, before a plan is
built. None accepts any build.
NonDurableRuntimeError
¶
Bases: TypeError
A caller attempted to serialize runtime-only injected state.
OutputSelection
¶
Bases: ConfigurationModel
Requested named outputs and reducer, separate from model and biological inputs.
ReferenceGenomeRunInputs
¶
Bases: ModelRunInputs
Per-run inputs for models whose results depend on staged reference FASTA bytes.
ResourceReference
¶
Bases: ConfigurationModel
Durable identity for a model, weights, genome, or other resource.
digest is a content address and takes precedence over location metadata in scientific cache identity.
It addresses the resource bytes as narrowed by any subtype selectors; a selector covering multiple files
therefore needs a bundle or snapshot digest. Every additional subtype field is identity-bearing, so keep
operational location metadata in uri rather than adding fields such as region or endpoint. If no
digest is available, an immutable provider revision plus URI is the next-best identity. A bare URI remains
supported for legacy inputs, but identifies only the name, not the bytes later served there.
scientific_dict
¶
Return the strongest identity plus any subtype-specific selectors.
A digest identifies the selector-narrowed resource without its location. Revision-based identities retain the URI, and subclasses retain identity-bearing selectors such as a filename within a versioned repository.
RuntimeContext
¶
Explicitly non-durable injected clients/functions used only while executing a plan.
SavedConfiguration
¶
SecretReference
¶
Bases: ConfigurationModel
Durable pointer to a credential; it never contains the credential value itself.
SubjectSelection
¶
TrainingAssemblyConfiguration
¶
Bases: ModelConfiguration
A model configuration that records the assembly the model was trained on.
A binding whose plugin lists training_coordinate_fields subclasses this instead of ModelConfiguration.
training_genome_build is the training assembly, such as "mm10" for a model trained on mouse data. It
describes the model, not a run: a run reads the reference sequence of its variants' assembly
(ModelRunInputs.genome_build) whatever the training assembly is. When the two differ, the plugin's
training_coordinate_fields are stored as null. Aliases normalize as canonical_genome_build does.
None leaves the training assembly undeclared, and the run is treated as same-assembly. An undeclared
training assembly is omitted from the saved form (to_dict(), to_json()) and from
scientific_dict(), so configurations saved without one keep their hashes. A score identity also omits a
declared training assembly equal to the run's genome_build, so declaring the assembly a model already
scores on keeps its lineage. A training assembly that differs from the run's is part of the lineage.
ContainerResultFiles
dataclass
¶
Collected native files for the primary table, one named detail table, or one named artifact.
name is "primary", a manifest-declared :class:DetailSchema name, or the name of an
:class:ArtifactSchema the run's output selection names. Logical paths refer to terminal task outputs
before a deployment maps their storage URIs. Keeping this classification in the portable plan prevents
result codecs from guessing meaning from provider-specific paths or filenames; an artifact's files are
never decoded at all, only digested and stored.
ContainerScoringPlan
dataclass
¶
ContainerScoringPlan(
shards: list[ContainerTaskSpec],
plugin_identity: PluginRunIdentity,
summarize: ContainerTaskSpec | None = None,
ready_when: int = 1,
result_files: tuple[ContainerResultFiles, ...] = (),
)
A scoring run expressed as N container shards, plus an optional fan-in summarize shard.
This is the container form of ScoringPlan, used by architectures like ChromBPNet, ProCapNet, and
Cherimoya. Each shard is a ContainerTaskSpec that runs on any ExecutionBackend (local, Modal, or
Kubernetes), so the same plan scores on any of them. ready_when is the number of shards to wait for
before the summarize shard runs; it equals ModelPlugin.num_folds. result_files assigns collected
terminal logical paths to the primary table, manifest-declared named details, or the artifacts the
request's output selection names. It may be omitted only for the backward-compatible primary-only shape,
where every terminal output is primary.
InlineScoringPlan
dataclass
¶
InlineScoringPlan(
plugin_identity: PluginRunIdentity,
executor: str,
payload: dict[str, JsonValue],
)
A durable inline execution descriptor, such as an AlphaGenome API scoring request.
The plan contains only JSON data and an executor discriminator. Runtime clients, secret resolvers, and
injected callables are supplied separately to ModelPlugin.execute_inline and never become plan state.
InterpretationRequest
dataclass
¶
InterpretationRequest(
run_id: str,
model_id: str,
configuration: ModelConfiguration,
run_inputs: ModelRunInputs,
resolver: PathResolver,
)
The inputs build_interpretation_plan needs to turn one (interpret-run, model) pair into an
InterpretationPlan. Like ScoringRequest, it is backend-agnostic: the binding names base-relative
logical paths and the backend PathResolver supplies the mount root. Interpretation outputs are
architecture-specific, so the binding owns its logical layout; core carries no interpretation layout.
run_id is the interpretation run's UUID, not a job id.
ModelPlugin
¶
Bases: ModelResults
One model architecture's full behavior: the results methods inherited from ModelResults, plus the
optional compute methods num_folds and the build_* plan builders. model_type remains the registry
key and model-family discriminator; manifest is the durable versioned identity. This is the class an
architecture author subclasses and registers.
model_type equals the model's stored architecture type (for example "CHROMBPNET"). Every other
plugin axis keys on a name discriminator; this one keeps model_type because the value is stored and
used elsewhere and cannot be renamed freely.
The compute methods are optional. By default they raise CapabilityNotSupported, so a plugin whose
scores are produced elsewhere can implement none of them.
Validate Altar API compatibility before this plugin can execute or interpret data.
equivalence_rules_id
property
¶
Hash of the rules format, rule data, and version bridges, recorded with each equivalence resolution.
num_folds
property
¶
Number of container shards one scoring run fans into (ChromBPNet uses 5; a single-shard or inline
model uses 1). This sets ContainerScoringPlan.ready_when and the number of shards the completion
fan-in waits for. Defaults to 1.
configuration_manifest
classmethod
¶
configuration_manifest() -> ConfigurationManifest
Return stable plugin/schema identity plus the two discoverable public models.
configuration_schema
classmethod
¶
Return this plugin's durable-configuration JSON Schema without loading a model SDK.
run_input_schema
classmethod
¶
Return this plugin's per-run biological-input JSON Schema.
parse_configuration
¶
parse_configuration(
value: Mapping[str, object] | ModelConfiguration,
) -> ModelConfiguration
Validate new-format durable configuration and reject unknown fields.
parse_run_inputs
¶
parse_run_inputs(
value: Mapping[str, object] | ModelRunInputs,
) -> ModelRunInputs
Validate new-format per-run inputs and reject unknown fields.
A plugin that sets reads_reference_genome to False gets its run inputs without genome: the model never
reads the reference, so neither its plans nor its identity may depend on which one the caller supplied.
parse_configuration_as
¶
parse_configuration_as(
value: Mapping[str, object] | ModelConfiguration,
model: type[C],
) -> C
Parse value as this plugin's configuration and return it typed as model.
A plan builder receives ScoringRequest.configuration typed as the base ModelConfiguration. This
validates it through parse_configuration and returns it as the binding's own class, which must be
configuration_model or one of its bases, so the binding reads its fields without a cast.
parse_run_inputs_as
¶
parse_run_inputs_as(
value: Mapping[str, object] | ModelRunInputs,
model: type[R],
) -> R
Parse value as this plugin's run inputs and return it typed as model; see parse_configuration_as.
validate_output_selection
¶
validate_output_selection(
output: OutputSelection,
) -> OutputSelection
Reject output/reducer choices the plugin would otherwise silently ignore.
unavailable_score_fields
¶
unavailable_score_fields(
configuration: Mapping[str, object]
| ModelConfiguration,
run_inputs: Mapping[str, object] | ModelRunInputs,
) -> frozenset[str]
Return the primary score fields a run of configuration on run_inputs stores as null.
A field in training_coordinate_fields is computed from coordinates on the assembly the model was
trained on, such as whether a variant lies in one of the model's own peaks. A plugin that lists such
fields uses a TrainingAssemblyConfiguration. When the configuration declares a
training_genome_build and the run's genome_build (the variants' assembly) names another assembly,
those coordinates do not describe the variants, so every such field is returned.
Otherwise the result is empty. Aliases compare equal, so GRCm38 and mm10 are one assembly.
The scoring engine nulls these fields in every primary row before it validates and stores them. A host that ingests a runtime's output by its own path must null the same fields.
scoring_result_codec
¶
scoring_result_codec() -> ScoringResultCodec
Return the binding-owned decoder for collected container outputs.
The default accepts a headered TSV containing variant_id plus exactly the manifest's primary
result fields. Bindings override this when a runtime uses different source names or emits explicitly
ignored transport fields. Storage adapters never learn either runtime-file shape.
detail_result_codec
¶
detail_result_codec(name: str) -> DetailResultCodec
Return the binding-owned decoder for one collected container detail result.
The default accepts exact-schema TSV output. Bindings override this method when their runtime uses
native column names, while the engine remains responsible for selecting only the logical files that
the plan assigned to name.
save_configuration
¶
save_configuration(
configuration: ModelConfiguration,
) -> SavedConfiguration
Wrap validated configuration with the plugin/schema identity needed after a restart.
load_configuration
¶
load_configuration(
saved: SavedConfiguration | str,
) -> ModelConfiguration
Validate identity/version, migrate if needed, and rebuild typed configuration.
migrate_configuration
¶
migrate_configuration(
from_version: str, configuration: Mapping[str, object]
) -> Mapping[str, object]
Migration seam for older saved schema versions; plugins override when they add one.
convert_legacy_artifact
¶
convert_legacy_artifact(
artifact: Mapping[str, object], *, genome_build: str
) -> LegacyScoringConversion
Explicit compatibility seam; arbitrary old mappings are never accepted implicitly.
scoring_layout_class
¶
scoring_layout_class() -> type[ScoringLayout]
Return the ScoringLayout class this plugin's scoring requests carry.
A durable request records only the layout's field values, never a class path, so the plugin names the
class that reads them back: a binding whose plan needs extra layout settings subclasses ScoringLayout
with those settings as dataclass fields and returns that subclass here. serialize_scoring_request
accepts exactly this class, so a request can never round-trip to a different layout than it was built
with. The default is the model-neutral ScoringLayout.
serialize_scoring_request
¶
serialize_scoring_request(request: ScoringRequest) -> str
Serialize a validated request with configuration, layout, and plugin identity.
deserialize_scoring_request
¶
deserialize_scoring_request(value: str) -> ScoringRequest
Rebuild a durable request after a process restart.
The layout is rebuilt as scoring_layout_class() from the recorded field values. An envelope without a
layout entry predates layout serialization; every such request carried the plugin's layout with its
default field values, so that is what it rebuilds.
with_run_variants
¶
with_run_variants(
request: ScoringRequest, variants: Sequence[VariantKey]
) -> ScoringRequest
Return a copy of request whose run inputs carry exactly variants, in order.
prepare_scoring_batches calls this for an inline plan after it has deduplicated the candidate cohort,
set aside ineligible variants, and removed cache hits: each dense chunk of the remaining variants
becomes one executable request through this hook. The returned request may differ from request
only in its run inputs, and the scoring plan built from it must carry the same scientific identity,
because variants are per-run biology and never part of the model-instance identity (invariant 8).
Only a binding whose run inputs hold the variants to score overrides this, together with
run_variant_ids, which reads them back. The default raises CapabilityNotSupported: a container plan
takes its variants from the staged variant file, which preparation writes for it, so its run inputs
never carry them.
run_variant_ids
¶
run_variant_ids(
run_inputs: ModelRunInputs,
) -> Sequence[str] | None
Return the canonical IDs of the variants run_inputs carry, in order, or None if they carry none.
This reads back what with_run_variants wrote. run_scoring calls it for an inline plan. A primary or
detail row for a variant outside the returned IDs raises ScoringOutputError. The returned variants
without a primary row are counted in ScoringRunResult.variants_without_rows. None skips both checks.
A binding that overrides with_run_variants overrides this too. The default returns None. A container
plan's variants come from its staged variant file, so a container binding leaves the default.
Provisional: the hook is expected to change.
execute_inline
async
¶
execute_inline(
plan: InlineScoringPlan,
runtime: RuntimeContext | None = None,
) -> list[dict[str, Any]] | InlineScoringResult
Execute a durable inline descriptor using separately injected runtime state.
run_identity
¶
run_identity(
runtime_identities: Mapping[str, str],
*,
reducer: str | None = None,
) -> PluginRunIdentity
Snapshot plugin/output/runtime identity independently of downstream prioritization.
scoring_run_identity
¶
scoring_run_identity(
runtime_identities: Mapping[str, str],
*,
configuration: ModelConfiguration,
output: OutputSelection,
run_inputs: ModelRunInputs,
) -> PluginRunIdentity
Snapshot the exact model instance and scoring semantics for persisted results.
Durable model configuration (including weights/resources), the complete output selection, and genome
inputs affect result meaning and therefore the cache identity. The method derives both genome build
and structured genome identity from run_inputs so a binding cannot silently omit a supplied
genome resource; a plugin that reads no reference genome (reads_reference_genome) records the build
only, whatever reference the caller supplied. The exact hash retains resource locations; the scientific
projection prefers content digests and excludes typed credential references from compatibility.
Per-run subjects, job/model IDs, batch boundaries, path resolvers, and runtime clients deliberately
do not prevent incremental scoring into the same model result set. Every scientific field comes from
scoring_lineage_descriptor, so an identity and its descriptor cannot disagree.
scoring_lineage_descriptor
¶
scoring_lineage_descriptor(
runtime_identities: Mapping[str, str],
*,
configuration: ModelConfiguration,
output: OutputSelection,
run_inputs: ModelRunInputs,
) -> LineageDescriptor
Return the unhashed inputs of the lineage ID scoring_run_identity gives the same arguments.
The descriptor's configuration is the scientific projection whose hash is the identity's
scientific_configuration_hash; it carries no resource locations or credentials.
scoring_runtime_identities
¶
scoring_runtime_identities(
configuration: ModelConfiguration,
) -> dict[str, str]
Return the runtime identities a scoring plan built from configuration records, by runtime name.
Plan builders call this rather than spelling the mapping inline, so a host can derive a plan's lineage
with scoring_lineage_descriptor_for without knowing the binding. A binding whose manifest declares a
runtime overrides it, typically as {"model_runtime": configuration.image}. The default answers only
for a manifest that declares no runtimes and otherwise raises CapabilityNotSupported.
scoring_lineage_descriptor_for
¶
scoring_lineage_descriptor_for(
request: ScoringRequest,
) -> LineageDescriptor
Return the lineage descriptor of the plan build_scoring_plan(request) would build, without building it.
equivalence_projection
¶
equivalence_projection(
descriptor: LineageDescriptor,
) -> dict[str, Any]
Return the part of descriptor that decides scientific equivalence between lineages.
Lineages whose projections are equal are the same computation and may reuse each other's scores. The
default is the whole descriptor, so only lineages with the same ID match. A projection may never drop
or change the plugin, output selection, schema, or genome, and may change plugin_version only as
equivalence_version_bridges declares; lineage_equivalence_key enforces both. Rule data the
projection reads belongs in equivalence_rules, so that equivalence_rules_id changes with it.
equivalence_rules
¶
Return the rule data equivalence_projection applies, such as equivalence classes; None by default.
Sequences are treated as unordered sets when the rules are hashed into equivalence_rules_id.
build_scoring_plan
¶
build_scoring_plan(request: ScoringRequest) -> ScoringPlan
Turn one (model, job) pair into a ScoringPlan — the runtime image, argv, and I/O for each shard.
The model-specific knowledge (the subcommand, the flag names, the per-fold path math) lives here,
while the returned ContainerTaskSpec shards run on any ExecutionBackend. Paths come from
request.layout (logical paths) combined with request.resolver (the mount root), so the plan is
backend-agnostic: one plan runs unchanged locally or on Modal.
The default raises CapabilityNotSupported, since a results-only plugin has no plan. Container
architectures override this to return a ContainerScoringPlan; inline ones such as AlphaGenome
return an InlineScoringPlan.
build_interpretation_plan
¶
build_interpretation_plan(
request: InterpretationRequest,
) -> InterpretationPlan
Turn one (interpret-run, model) pair into a staged interpretation workflow.
The binding chooses the named stages and their dependencies. Model-specific commands and resources live in its backend-neutral container tasks; core does not assume folds, motifs, plots, or another particular interpretation shape.
The default raises CapabilityNotSupported; only container architectures with an interpretation
pipeline override it.
build_preprocessing_plan
¶
build_preprocessing_plan(
request: PreprocessingRequest,
) -> PreprocessingPlan
Turn one model into an optional staged preparation workflow.
Preparation derives reusable model artifacts before scoring; it is not model training. The binding chooses its stage graph and optional provenance outputs. Scoring remains free to consume trusted, externally managed artifacts without an Altar-produced provenance manifest.
The default raises CapabilityNotSupported; only container architectures with a preprocessing step
override it.
prepared_run_inputs
¶
prepared_run_inputs(
request: ScoringRequest,
*,
preparation_run_inputs: ModelRunInputs,
published: Mapping[str, Path],
) -> ModelRunInputs
Return the run inputs to score with when altar prepare published this model's files.
altar run calls this once per model section whose platform inputs a successful altar prepare
published, before it builds the model's scoring plan. A binding turns on its own check of those files
here, such as a flag that makes its runtime compare them with a manifest. It raises ValueError when
the files cannot serve request, and the run then stops before it reads the cohort.
preparation_run_inputs are the run inputs preparation ran with, as its publication recorded them.
published maps each published logical path to its local file. The reference digest in
request.run_inputs may be a placeholder, because the run verifies the reference after this call and
then fills in its digest. The returned run inputs must therefore not depend on that digest.
The default returns request.run_inputs unchanged. Run inputs do not enter a score's identity, so
this hook cannot change a lineage.
Provisional: the hook is expected to change.
ModelResults
¶
Bases: ABC
The results half of a model architecture: the methods the score store uses to build one wide row per variant.
These are split out from the compute methods so a caller can depend on only this narrower contract. The
data-lake driver's ScoredModel.plugin is typed as ModelResults rather than the full plugin, so it
can only call these methods and never reach a build_*.
score_columns defines the column schema. prioritize_predicate is the rule that flags a variant as
prioritized, rendered to SQL or Python. to_model_score builds one model_scores JSONB entry.
score_columns is final and derives the columns from the manifest's result schema; to_model_score
defaults to the same schema, so prioritize_predicate is the only results method a subclass must
implement. prioritize is a plain-boolean convenience over
prioritize_predicate; note that core's materialize path does not call it — it evaluates the
predicate directly to keep the three-valued (Kleene) result (see prioritize below). A full
ModelPlugin adds the compute methods on top of this base.
validate_result_identity
¶
validate_result_identity(
identity: PluginRunIdentity,
) -> None
Fail before this results implementation decodes an incompatible primary score row.
Prioritization is applied after raw scores are read, so its exact expression remains provenance but is not part of primary-score compatibility. A changed policy can rematerialize the same raw scores. Runtime, configuration, output-selection, reducer, and genome compatibility belong to the concrete persisted result and are therefore checked by the score store, not against this wrapper's defaults.
score_columns
¶
score_columns() -> list[ScoreColumn]
Return the per-variant score columns, derived from the manifest's result schema.
The manifest's ordered ResultSchema is the single source for the column schema: a ScoreColumn is a
ResultField without its biological meaning, and ModelResultContract and the scoring engine both
require the two to match exactly. The method is final. A subclass that defines its own score_columns
is rejected when the class is created, so a column can only be added, removed, or retyped by changing
the manifest, which is what versions the result schema.
prioritize_predicate
abstractmethod
¶
prioritize_predicate() -> Predicate
The prioritization rule as a Predicate. It renders to SQL, so the score store can filter with it,
or to Python for the reference store. Its columns may reference both score columns and annotation
columns.
to_model_score
¶
Build one model_scores JSONB entry from this model's per-variant score mapping.
The entry's keys are model_id, model_name, one key per score_columns() entry in order, and
prioritized. The default decodes each score value as its column's declared dtype. A missing, None,
or NaN value becomes None for every dtype: the default never turns an absent measurement into
False, 0, or an empty string, so a store can still tell "not measured" from a measured negative.
Decoding is strict, so a schema mismatch fails instead of producing a plausible wrong value. A
NumPy-style scalar (from a pandas frame) is unwrapped first. float accepts integers and floats but
not booleans. int accepts integers and whole floats, because a frame stores an integer column with
missing values as float, and rejects 3.7. bool accepts booleans and the integers 0 and 1, which
is how SQLite stores a flag. str accepts only strings. Any other value raises TypeError or
ValueError naming the column.
prioritized follows a different rule because it is the materialized per-model decision, not a score.
The materialize path passes the predicate's three-valued result, and a None (a required input was
absent) becomes False. That matches prioritize() and the warehouse export's
COALESCE(is_prioritized, FALSE), so both materialization paths produce the same entry. A present
value is decoded with the strict bool rule.
Override this only when a stored value needs a model-specific decoding. Changing how a stored value is decoded is a breaking result change (see the plugin ABI guide).
prioritize
¶
Evaluate prioritize_predicate against the merged score and annotation values as a plain boolean.
Score and annotation names must be disjoint. A collision raises SchemaCollisionError instead of
silently choosing one producer's value.
This is a convenience for callers who want a definite yes/no. It goes through to_python(), which
collapses the predicate's three-valued (Kleene) result — a missing/None column yields None — down
to False, matching a SQL boolean filter where only a definite True counts.
Core's materialize path does not call this. It evaluates the predicate with
prioritize_predicate().evaluate(...) (see data_lake/materialize.py), which returns the raw
True/False/None, then threads that value into to_model_score and aggregates the row-level flag
with an is True test. The net prioritized outcome matches prioritize() today — to_model_score
performs the same None→False collapse, and None is True is False — so the two do not disagree;
the difference is only where the collapse happens. Keeping the Kleene value until to_model_score
leaves a to_model_score implementation free to treat "the rule did not fire" (False) and "a
required input was absent" (None) differently. Prefer evaluate when that distinction matters;
prioritize is the shortcut when it does not.
PreprocessingRequest
dataclass
¶
PreprocessingRequest(
model_id: str,
configuration: ModelConfiguration,
run_inputs: ModelRunInputs,
resolver: PathResolver,
)
The inputs build_preprocessing_plan needs to turn one model into a PreprocessingPlan.
Like ScoringRequest, it is backend-agnostic: the binding names base-relative logical paths and the
backend PathResolver supplies the mount root. Derived artifacts are architecture-specific, so the binding
owns its logical layout; core carries no preprocessing layout. Staged file names come from the typed
configuration, with no runtime directory listing.
ScoreColumn
dataclass
¶
One per-variant score column a model plugin produces.
Declaring the column here sets four things that must otherwise be kept in sync by hand: the score-store schema (table columns / DDL), the write-time validator, the wide-TSV column names, and the frontend column definitions.
It lives in this shared leaf module — not in model/plugin.py — because it is the schema the score
store consumes (ScoreStore.ensure_schema / add_scores); keeping it here lets the data-lake axis
name it without importing back into the model axis. model.plugin re-exports it for architecture
authors.
ScoringRequest
dataclass
¶
ScoringRequest(
job_id: str,
model_id: str,
configuration: ModelConfiguration,
run_inputs: ModelRunInputs,
resolver: PathResolver,
output: OutputSelection,
scoring_batch: int | None = None,
scoring_batch_count: int | None = None,
layout: ScoringLayout = ScoringLayout(),
)
The inputs build_scoring_plan needs to turn one (model, job) pair into a ScoringPlan.
Paths are described independent of any backend, so a plugin can build the plan for any backend: they
come from a ScoringLayout (a base-relative logical layout) combined with the backend's PathResolver
(the mount root), never a concrete filesystem. configuration holds durable model/resource identity;
run_inputs holds per-run biology; output holds reducer/output selection. Runtime-injected clients
and callables are supplied separately and cannot enter this request. layout is an instance of the
plugin's ModelPlugin.scoring_layout_class; its dataclass fields are serialized with the request and read
back into that class.
genome_label
property
¶
Compatibility spelling for the typed run input's genome build.
DelimitedResultCodec
dataclass
¶
DelimitedResultCodec(
schema: ResultSchema,
source_names: Mapping[str, str] = dict(),
row_identity_fields: Mapping[str, str] = dict(),
allowed_extra_fields: tuple[str, ...] = (),
identity_field: str = "variant_id",
delimiter: str = "\t",
null_tokens: tuple[str, ...] = ("", "NA", "NaN", "nan"),
optional_extra_fields: tuple[str, ...] = (),
)
Strict decoder for a headered delimited primary-result file.
source_names maps each declared result name to its runtime-file spelling. row_identity_fields
maps transport columns such as chr/pos/ref/alt to scalar dtypes and preserves them for
storage adapters that need decomposed loci. allowed_extra_fields names required runtime columns that
are intentionally ignored; optional_extra_fields names ignored diagnostics accepted when present.
Every other undeclared column is rejected. This makes both preservation and projection explicit binding
decisions instead of silently dropping new runtime output.
decode
async
¶
decode(
storage: Storage,
output_uris: Sequence[str],
*,
batch_size: int = 10000,
) -> AsyncIterator[ResultBatch]
Stream every collected file in order and validate its complete input schema.
ScoringResultCodec
¶
Bases: Protocol
Decode collected runtime outputs into bounded, schema-shaped primary batches.
decode
¶
decode(
storage: Storage,
output_uris: Sequence[str],
*,
batch_size: int = 10000,
) -> AsyncIterator[ResultBatch]
Yield decoded batches without loading a complete output into memory.
ModelArtifactLayout
dataclass
¶
Paths to shared, model-owned inputs: the staged genome FASTA and files under models/{model_id}.
These live at the storage root under genomes/ and models/, not inside any job directory. Paths are
POSIX and relative to the storage root; the backend's PathResolver supplies the mount root. A binding
that needs architecture-specific model files (derived calibration data, an interpretation motif set, and
so on) names them with model_resource_file or subclasses this layout in its own package.
model_resource_file
¶
Return a fixed model-owned resource path, models/{model_id}/{filename}.
Bindings use this for content-addressed weight bundles, track catalogs, derived model artifacts, and similar resources. They supply a constant basename chosen from declared configuration rather than a provider path or URI suffix; rejecting path components keeps the logical layout portable and prevents traversal.
fold_model_file
¶
Path to one cross-validation ensemble member's weights, models/{model_id}/fold_{fold}_model{ext}.
ext includes the leading dot, e.g. .h5. Derive it from the binding's declared weight format, never
from a resource URI: a content-addressed URI need not carry a file extension.
ScoringLayout
dataclass
¶
Bases: ModelArtifactLayout
Model-neutral paths for one container scoring run, one method per file a scoring plan names.
Adds the scoring job's inputs and outputs on top of the shared genome and model-file paths from
ModelArtifactLayout. ScoringRequest.layout defaults to this class; the scoring engine and the portable
preparation path read the variant input and result paths from it.
ineligible_variants_file
¶
Return the report of candidates that batch preparation excluded as ineligible for this model.
fold_score_file
¶
Return one ensemble member's intermediate score file, reduced by the plan's summary task.
scoring_result_file
¶
Return the logical path of the primary result table the scoring engine collects.
detail_result_file
¶
detail_result_file(
job_id: str,
model_id: str,
name: str,
scoring_batch: int | None = None,
) -> str
Return the logical TSV path for one manifest-declared named detail result.
artifact_result_file
¶
artifact_result_file(
job_id: str,
model_id: str,
name: str,
scoring_batch: int | None = None,
*,
extension: str = "",
) -> str
Return the logical path for one manifest-declared, batch-scoped artifact output.
extension is the file suffix including its dot (.npz, .parquet); the layout does not know the
artifact's media type, so the binding names it. The scoring engine never decodes the file: it is
collected, digested, and handed to the artifact store as it is.
artifact_variant_result_pattern
¶
artifact_variant_result_pattern(
job_id: str,
model_id: str,
name: str,
scoring_batch: int | None = None,
*,
extension: str = "",
) -> str
Return the logical path pattern of a variant-scoped artifact: one file per variant of the batch.
The pattern is jobs/{job}/results/{model}[/batch_{n}]/{name}/{row}{extension}, where
:data:VARIANT_ROW_PLACEHOLDER ({row}) stands for the zero-based row of the variant in the batch's
variant file. A plan cannot name the files itself, because it is built before the batch's variants are
known, so it declares this pattern as the artifact's one terminal output and passes its resolved form to
the runtime, which writes one file per row by replacing {row} with the row number
(:func:variant_artifact_path). :func:~altar.scoring.executable_scoring_plan expands the pattern
against the staged variant file before submission, and each collected file is recorded as
covering its row's variant (:func:~altar.scoring.container_artifact_coverage). A row number, not the
variant ID, names the file: an ID holds both alleles, so it has no length bound a filename can rely on.
ModelWorkflowPlan
dataclass
¶
ModelWorkflowPlan(
operation: str,
stages: tuple[WorkflowStage, ...],
plugin_identity: PluginRunIdentity,
outputs: tuple[Transfer, ...] = (),
)
A backend-neutral DAG for one optional model operation.
operation is a stable plugin-facing discriminator such as "preparation" or
"interpretation". Each stage runs all of its tasks in parallel after every stage in needs has
completed. outputs names the terminal artifacts the caller wants copied back through the backend.
Intermediate products may remain on the backend's shared working volume.
WorkflowExecutionError
¶
WorkflowExecutionError(
message: str,
*,
completed_stages: tuple[str, ...] = (),
collected_outputs: tuple[str, ...] = (),
)
Bases: RuntimeError
A model-workflow task failed on its execution backend, or a stage did not finish in time.
completed_stages names the stages whose every task succeeded before the failure, in the order they finished.
collected_outputs holds the URIs of the terminal outputs those stages wrote, as collected. Both are empty
unless the workflow ran with collect_completed=True. Provisional: the attributes are expected to
change.
WorkflowRunResult
dataclass
¶
WorkflowRunResult(
plan: ModelWorkflowPlan,
completed_stages: tuple[str, ...],
output_uris: tuple[str, ...],
)
The completed stages and collected terminal artifact locations for one workflow.
WorkflowStage
dataclass
¶
WorkflowStage(
name: str,
tasks: tuple[ContainerTaskSpec, ...],
needs: tuple[str, ...] = (),
)
One parallel task set whose declared prerequisite stages must finish first.
canonical_chromosome
¶
Return the canonical chr-prefixed spelling used in portable keys.
Primary chromosomes accept common aliases (1/chr1/CHR01 and
M/MT/chrM) in any case. Other reference contigs keep their exact
spelling after an optional case-insensitive chr prefix is normalized, so
CHRUn_KI270302v1 becomes chrUn_KI270302v1 but chrun_KI270302v1
stays as written. Non-ASCII text, whitespace inside the name, and characters
outside the VCF contig-name set (including :) raise
VariantIdentityError. This is a naming rule only; it does not claim that
contigs from different assemblies are interchangeable.
canonical_variant_id
¶
canonical_variant_id(
chromosome: str,
position: int,
reference_allele: str,
alternate_allele: str,
) -> str
Return the canonical text key for decomposed one-based locus fields.
sha256_file
¶
Return the sha256:<hex> digest of the bytes at path, reading it in bounded chunks.
verify_file
¶
verify_file(
path: str | PathLike[str],
expected: str,
*,
label: str = "resource",
trust_record: bool = False,
record: bool = False,
) -> bool
Raise DigestMismatchError unless path is one regular file whose bytes have digest expected.
expected must be a canonical SHA-256 digest; a malformed one raises ValueError. label names
the file in the error message.
By default the file is always hashed. With trust_record, a current verification record accepts the file
without reading it, so a file staged once and read by many tasks is hashed once. With record, a
successful hash writes a record for later checks. Anyone who can write the storage can also write a record,
so trust records only on storage whose writers you trust, and never where bytes first arrive (a download).
Returns True when the file was hashed and False when a record accepted it.
generated_lineage_id
¶
generated_lineage_id(identity: PluginRunIdentity) -> str
Return the ID of the lineage a scoring run writes under: the hash of its scientific projection.
This is the ID :meth:ScoreLineage.from_run assigns, so a detail store can record the lineage of the run
that produced a table without being handed the run's output columns.
canonical_genome_build
¶
Return Altar's spelling of label: GRCh38 and hg38 both give hg38.
Surrounding whitespace is stripped. A known label matches in any letter case. A known assembly with a GRC patch
suffix (GRCh38.p14, GRCm38.p6) or a reference-set suffix (mm10_no_alt, hg38_no_alt_analysis_set,
GRCh38_full_analysis_set_plus_decoy_hla) gives that assembly, since it names the same coordinates. Any other
label is returned stripped and otherwise unchanged. An empty label raises ValueError.
require_known_genome_build
¶
Return the canonical spelling of label, raising UnknownGenomeBuildError if Altar does not know it.
same_genome_build
¶
Return whether two labels name the same assembly once aliases are normalized.
lineage_equivalence_key
¶
lineage_equivalence_key(
plugin: ModelPlugin, descriptor: LineageDescriptor
) -> str
Return the key under which plugin treats descriptor's lineage as scientifically equivalent.
Two lineages are equivalent when their keys are equal. The key is the hash of the plugin's
equivalence_projection(descriptor). A projection that drops or changes plugin_id,
output_selection_hash, schema_hash, genome_build, or genome_hash is refused, and so is one
that changes plugin_version other than as the plugin's equivalence_version_bridges declares. The one
exception is a plugin that reads no reference genome (reads_reference_genome): its projection may set
genome_hash to None, since the reference an older lineage recorded never reached the model. Its
genome_build remains a boundary.
canonical_json
¶
Return canonical UTF-8 JSON text: sorted object keys, compact separators, no NaN.
classify_variant
¶
classify_variant(key: VariantKey) -> VariantClass
Return the :class:VariantClass of key from its REF and ALT lengths.
Classification trusts that both alleles are literal bases. A placeholder allele such as - or * would
count as one base; rejecting those is :class:VariantKey's job, not this function's.
deterministic_hash
¶
Return a lowercase SHA-256 identity over :func:canonical_json.
validate_result_identity
¶
validate_result_identity(
manifest: PluginManifest, identity: PluginRunIdentity
) -> None
Reject a stored primary result before the current plugin assigns it new meaning.
This validates the binding-owned portion of primary-score compatibility. Concrete model configuration,
runtime, output, reducer, and genome are compared by stores through :class:ResultCompatibility.
Prioritization belongs to materialization rather than score identity.
require_resource_digests
¶
require_resource_digests(
value: ConfigurationModel, *, owner: str
) -> None
Raise ValueError unless every resource on value carries a SHA-256 digest.
Checks each top-level field whose value is a ResourceReference or a tuple or list of them; an unset
optional resource (None) is skipped. Nested configuration models and mappings are not traversed, so a
configuration that nests resources must also check the nested model. Missing resources are named in
field order, with an index for a sequence (weights[2]), and owner prefixes the message. Call it
from a model_validator(mode="after") on a configuration whose runtime verifies staged bytes, so
Pydantic reports the failure as a validation error before a plan can be built.
require_strictly_increasing
¶
require_strictly_increasing(
values: Sequence[int],
*,
owner: str,
field: str,
minimum: int,
maximum: int,
) -> None
Raise ValueError unless values is non-empty, strictly increasing, and within [minimum, maximum].
A selection of model outputs (track or target indices) or of augmentation offsets is canonical only when
it is strictly increasing: equivalent selections then cannot acquire different cache identities from their
order or from repeats, and a value the model does not have fails at configuration instead of inside a
container. owner and field name the configuration and field in the message. Call it from a
model_validator(mode="after"), as with require_resource_digests.
single_container_plan
¶
single_container_plan(
plugin: ModelPlugin,
request: ScoringRequest,
*,
kind: str,
image: str,
command: Sequence[str],
resources: ResourceRequest,
inputs: Sequence[Transfer],
labels: Mapping[str, str] | None = None,
artifact_extensions: Mapping[str, str] | None = None,
) -> ContainerScoringPlan
Build a ContainerScoringPlan whose one task scores the request's variant batch.
inputs are the binding's resource transfers: weights, auxiliary files, and the genome. The task also
reads the batch's variant file at request.layout.model_variants_file(...) and writes the primary result
at scoring_result_file(...) plus one named detail file at detail_result_file(...) for every schema
in plugin.manifest.detail_schemas, and one file at artifact_result_file(...) for every artifact the
request's output selection names (:meth:~altar.models.PluginManifest.selected_artifact_schemas); an
unselected artifact gets no transfer, no classification, and no path in the command. A variant-scoped
artifact gets its artifact_variant_result_pattern(...) instead, which the runtime fills once per row of
the variant file and :func:~altar.scoring.executable_scoring_plan expands before submission.
artifact_extensions gives each declared artifact's file suffix ({"profiles": ".npz"}), since the
layout does not know media types; an artifact it omits has no suffix. Those transfers and the matching
result_files classification are added here, and command must name the resolved path
(request.resolver.resolve) of each of them as one argv element: a command that reads or writes
anywhere else would run against files the plan never stages or collects, so it is rejected before a plan
exists.
image is the manifest's one container runtime and must be the identity the plugin's
ModelPlugin.scoring_runtime_identities reports for it; the plan's identity comes from those runtime
identities and the request's configuration, output selection, and run inputs through
ModelPlugin.scoring_run_identity. The task is labelled with job_id, model_id, kind, and the
batch identity; labels adds binding-specific labels and may not redefine those.
get_model_plugin
¶
get_model_plugin(model_type: str) -> ModelPlugin
Look up and instantiate the ModelPlugin for a model architecture, keyed by its model_type string
(the registry key, e.g. "CHROMBPNET").
A call site holds a model's model_type and asks for its plugin without naming a concrete class, which
is what lets the scoring, interpretation, and preprocessing flows work with any architecture. Adding an
architecture then only requires registering it. The registry stores the plugin class (an entry point
loads the class object); this instantiates it, and plugins take no constructor arguments. Raises
KeyError, listing the registered names, if model_type has no plugin.
get_model_plugin_registry
¶
get_model_plugin_registry() -> PluginRegistry[
type[ModelPlugin]
]
Return the shared registry of model-architecture plugins. It stores ModelPlugin subclasses, so
.get(model_type) returns a type[ModelPlugin].
resource_transfer
¶
resource_transfer(
resource: ResourceReference,
logical_path: str,
*,
locality_key: str | None = None,
) -> Transfer
Declare a configured resource as a container input staged at logical_path.
The transfer carries the resource's uri as its location and its digest as the content identity the
staging backend verifies, so relocating identical bytes changes neither the plan's meaning nor its cache
identity. revision and subtype selectors stay in the configuration's scientific identity; a storage
adapter reads only the location and the digest. locality_key is the optional co-scheduling hint
described on Transfer, typically the model ID for model-owned resources.
scoring_plan_from_dict
¶
Rebuild a scoring plan, rejecting unknown envelope fields.
scoring_plan_from_json
¶
Rebuild a scoring plan after a process restart.
scoring_plan_to_dict
¶
Serialize either scoring-plan shape to JSON-compatible values.
scoring_plan_to_json
¶
Serialize a durable scoring plan to JSON.
variant_artifact_path
¶
Return the path of the file for row row of the batch's variant file under a per-variant pattern.
The placeholder must appear exactly once, in the pattern's basename. A runtime that does not import Altar
applies the same rule: replace {row} with the decimal row number, counting from zero.
run_model_workflow
async
¶
run_model_workflow(
plan: ModelWorkflowPlan,
*,
backend: ExecutionBackend,
input_transfer: TransferMapper | None = None,
output_transfer: TransferMapper | None = None,
spec_mapper: SpecMapper | None = None,
poll_interval_s: float = 5.0,
timeout_s: float = 86400.0,
progress: Callable[[str], None] | None = None,
collect_completed: bool = False,
) -> WorkflowRunResult
Execute all ready stages in dependency waves and collect declared terminal outputs.
The tasks of a wave are checked every poll_interval_s seconds. A failed task, or a wave with tasks still
open timeout_s seconds after it was submitted, stops the workflow and raises; every submitted task is
then cancelled through the backend. The time limit applies to each wave, not to the whole workflow.
progress, when given, receives short lines for a person: one when a wave is submitted, naming its stages
and the time limit, then the counts of its running, waiting and finished tasks when they change, at most
every 15 seconds, and at least once a minute. By default nothing is collected after a failure. With
collect_completed (provisional), the terminal outputs of every stage that finished before the failure are
collected first, one at a time, and the raised :class:WorkflowExecutionError names those stages and the
collected URIs, and quotes the end of each failed task's log the backend can read. An output a finished stage
did not write is skipped. A timeout is then raised as a
:class:WorkflowExecutionError too, chained to the TimeoutError.
workflow_plan_from_dict
¶
workflow_plan_from_dict(
data: Mapping[str, object],
) -> ModelWorkflowPlan
Rebuild and validate a workflow plan from durable values.
workflow_plan_from_json
¶
workflow_plan_from_json(value: str) -> ModelWorkflowPlan
Rebuild a durable model workflow plan from JSON.
workflow_plan_to_dict
¶
workflow_plan_to_dict(
plan: ModelWorkflowPlan,
) -> dict[str, Any]
Serialize a workflow plan to JSON-compatible values.
workflow_plan_to_json
¶
workflow_plan_to_json(plan: ModelWorkflowPlan) -> str
Serialize a durable model workflow plan to canonical JSON.