Skip to content

Add a model binding

A model binding is a package that teaches Altar one model architecture: what its scores mean, which settings change them, and how to compute them. It names no compute system, so the same binding runs on local Docker, Kubernetes or Modal.

When to choose a model binding

Write a model binding when the analysis runs inference: a model scores each variant during the run. Model or source? says when to write an annotation source instead, and Choose a result shape explains where each kind of output goes.

A binding produces scores in one of two ways:

  • A container binding runs the model's own command-line tool inside a container image. Altar stages the inputs, an execution backend runs the task, and Altar reads the result files back. Use it for a model that needs TensorFlow, PyTorch, weights or a GPU.
  • An inline binding scores in the Python process that calls Altar. Use it for a hosted API or a lightweight scorer. Add an inline model binding builds one, after steps 1 and 2 here.

The steps below build ExampleNet, a container binding. The code goes in a package laid out like this:

altar-examplenet/
  pyproject.toml
  altar_examplenet/__init__.py   (empty)
  altar_examplenet/plugin.py     (steps 1-3)
  tests/test_examplenet.py       (steps 5, 7 and 8)

You need pip install altar pytest pytest-asyncio. Altar's own test suite runs this page's code as written.

The interface

Subclass ModelPlugin, imported from altar.models. It is Stable. The class you register is the binding's plugin. It sets these class attributes and implements these methods:

Member Required? What it is
model_type required The registry name, and the name a run spec uses.
manifest required The PluginManifest: plugin ID, release, result schema, runtimes (step 1).
prioritize_predicate() required The rule that flags a variant, built from altar.predicates (step 3).
configuration_model, run_input_model default: empty configuration, ModelRunInputs The Pydantic models of the durable settings and the per-run inputs (step 2).
configuration_schema_id default None A stable ID for the configuration schema, saved with a configuration.
default_output default: OutputSelection() The output selection a run uses unless it names another.
build_scoring_plan(request) required to score Returns a ContainerScoringPlan (step 3) or an InlineScoringPlan. The default raises CapabilityNotSupported.
scoring_runtime_identities(configuration) required when the manifest declares runtimes The exact runtime of each role, such as the image digest.
scoring_result_codec(), detail_result_codec(name) default: headered TSV with the manifest's field names The decoders that read a container binding's result files into rows (step 4).
num_folds default 1 How many parallel tasks, such as one per fold, one container plan runs per batch.
validate_output_selection(output) default: accept default_output only Override to accept other reducers or artifact selections.
execute_inline(plan, runtime), with_run_variants(request, variants) required for an inline binding Compute an inline plan's rows, and put one batch's variants into a request; see Add an inline model binding.
run_variant_ids(run_inputs) provisional; default None Reads an inline batch's variants back, so the engine can check every row belongs to the batch.
reads_reference_genome provisional; default True Set it to False for a model that never reads the run's reference sequence.
build_preprocessing_plan(request) optional A preparation workflow that derives files from the configured resources.
prepared_run_inputs(request, ...) provisional; optional Adjusts run inputs when altar prepare published this model's files.
build_interpretation_plan(request) optional A generic workflow with operation "interpretation", run with run_model_workflow(). altar interpret runs an InterpretableModel instead.

A provisional member is expected to change; see Provisional names. The API reference documents every other member, such as equivalence_projection() and migrate_configuration().

1. Declare the manifest

Every model plugin declares a PluginManifest. Altar saves it with plans and results, so a newer release of the binding cannot silently reinterpret older rows. Start altar_examplenet/plugin.py with it:

from altar.models import (
    ApiVersionRange,
    PluginCapability,
    PluginKind,
    PluginManifest,
    PrioritizationPolicy,
    ResultField,
    ResultSchema,
    RuntimeIdentityPolicy,
    RuntimeKind,
    RuntimeRequirement,
    VariantClass,
    VariantEligibility,
)

EXAMPLE_MANIFEST = PluginManifest(
    plugin_id="org.example.examplenet.model",
    kind=PluginKind.MODEL,
    capabilities=frozenset({PluginCapability.SCORE, PluginCapability.MATERIALIZE_RESULTS}),
    architecture="ExampleNet",
    plugin_version="1.0.0",
    altar_api=ApiVersionRange("0.1.0", "0.2.0"),
    configuration_schema_version="1.0.0",
    result_schema=ResultSchema(
        version="1.0.0",
        fields=(ResultField("effect", "float", "Predicted effect", "Signed alternate-versus-reference effect"),),
    ),
    variant_eligibility=VariantEligibility(frozenset({VariantClass.SNV})),
    prioritization=PrioritizationPolicy("examplenet-effect", "1.0.0"),
    runtimes=(
        RuntimeRequirement(
            name="model_runtime",
            kind=RuntimeKind.CONTAINER_IMAGE,
            policy=RuntimeIdentityPolicy.DIGEST_REQUIRED,
        ),
    ),
)

What each part does:

  • plugin_id is a globally unique, reverse-domain name for the binding.
  • plugin_version is the binding's release.
  • altar_api is the range of Altar plugin API versions the binding works with. It is half-open: ApiVersionRange("0.1.0", "0.2.0") means 0.1.0 or later, before 0.2.0. Altar compares it with altar.models.ALTAR_API_VERSION, which is 0.1.0. That number is the version of the plugin interface, not of the altar package, and it changes only when the plugin interface changes. Altar refuses to load a plugin, or to run a saved plan, whose range excludes the running version.
  • configuration_schema_version and the result schema's version describe saved formats.
  • result_schema lists the primary result columns. Give each field its units, direction, nullability and biological meaning. It is the only column declaration: the inherited score_columns() is derived from it.
  • prioritization names and versions the rule that flags a variant, which step 3 defines.
  • runtimes names the runtime roles. DIGEST_REQUIRED accepts only an immutable name@sha256:... image.

The manifest describes every field, and Versioning says which changes need a new plugin_version or schema version. Read both before choosing schema, policy or runtime versions.

Variants the model can score

variant_eligibility declares the variant classes the runtime can score. VariantClass has four values: snv, mnv, insertion and deletion. It compares the lengths of REF and ALT as the key spells them, so A>AT and A>GT are both insertions. max_allele_length optionally limits the longer allele, in bases. Leave variant_eligibility out when the runtime handles every class itself, for example by returning a null row for a variant that doesn't fit its input window.

prepare_scoring_batches() sets ineligible variants aside and reports them before any cache lookup. It also sets aside a key that is not normalized (see Variant identity and normalization). The engine rejects result rows for ineligible variants (see Score a cohort). Eligibility filters inputs and doesn't change the score of any eligible variant, so it is not part of PluginRunIdentity or the score lineage. Keep the runtime's own check, because a batch can be staged by hand. Versioning says when widening or narrowing it needs a new plugin_version.

2. Declare configuration and run inputs

A model instance has two separate inputs, each a strict Pydantic model that rejects unknown fields:

  • the configuration holds the model's settings, which stay the same from run to run, such as weights, tracks and the image;
  • the run inputs hold the biology of one run: the assembly of its variants and the reference genome.

Add them to altar_examplenet/plugin.py:

from pydantic import model_validator

from altar.models import (
    ContainerImageDigest,
    ModelConfiguration,
    ReferenceGenomeRunInputs,
    ResourceReference,
    require_resource_digests,
)


class ExampleConfiguration(ModelConfiguration):
    weights: ResourceReference
    image: ContainerImageDigest

    @model_validator(mode="after")
    def require_content_addressed_resources(self) -> "ExampleConfiguration":
        require_resource_digests(self, owner="ExampleNet")
        return self


class ExampleRunInputs(ReferenceGenomeRunInputs):
    supported_genome_builds = frozenset({"hg38"})

A ResourceReference names a file by uri and digest. The digest is the scientific identity: Altar keys stored scores by it, so serving the same bytes from another location keeps the cache. The URI is only a location. require_resource_digests() rejects any ResourceReference field, or tuple of them, that lacks a SHA-256 digest, and names each one (weights[2]). Keep model-specific checks, such as distinct fold digests, in the same validator. Put a credential in a SecretReference field, never the credential itself. Altar leaves such a field out of the identity, so rotating a credential doesn't force rescoring.

ContainerImageDigest accepts only an immutable name@sha256:... image. The name follows the OCI reference grammar, [registry[:port]/]path[:tag]. A field default is not validated, so test that a binding's pinned default image passes.

ReferenceGenomeRunInputs is the run-input base for a model that reads reference sequence. It has two fields:

  • genome_build is the assembly of the run's variants, such as hg38. GRCh38 is accepted and stored as hg38. It is the build the run's scores are stored under.
  • genome is the reference FASTA, as a ResourceReference that must carry a digest. Its digest is part of the run's identity. The plan stages it at layout.genome_fasta(genome_build), which is genomes/hg38/genome.fasta.

supported_genome_builds lists the assemblies the model can read. Validation rejects any other genome_build. A model that reads no reference sequence, such as a hosted API, subclasses ModelRunInputs instead and sets reads_reference_genome = False on its plugin. Its run inputs then never carry a genome, so a reference a caller supplies changes neither its plans nor its identity, and altar run gives it none. The genome build still identifies its scores.

configuration.to_dict() is the complete saved configuration. configuration.scientific_dict() is the part that decides whether stored scores can be reused.

A model trained on another assembly subclasses TrainingAssemblyConfiguration and sets training_genome_build. It lists the primary fields it computes from its own training coordinates, such as whether a variant lies in one of its peaks, in training_coordinate_fields. The engine stores those fields as null when a run's variants are on another assembly. See Variant and training assemblies.

3. Build the container plan

The plugin class ties the manifest and models together and builds the scoring plan. Finish altar_examplenet/plugin.py with it:

from altar.execution import ResourceRequest
from altar.models import (
    ContainerScoringPlan,
    ModelPlugin,
    OutputSelection,
    ScoringRequest,
    resource_transfer,
    single_container_plan,
)
from altar.predicates import Abs, Col, Ge, Lit, Predicate


class ExamplePlugin(ModelPlugin):
    model_type = "EXAMPLE"
    manifest = EXAMPLE_MANIFEST
    configuration_schema_id = "org.example.examplenet.model.configuration"
    configuration_model = ExampleConfiguration
    run_input_model = ExampleRunInputs
    default_output = OutputSelection(reducer="alt_minus_ref_v1")

    def prioritize_predicate(self) -> Predicate:
        return Ge(Abs(Col("effect")), Lit(0.5))

    def scoring_runtime_identities(self, configuration: ModelConfiguration) -> dict[str, str]:
        return {"model_runtime": self.parse_configuration_as(configuration, ExampleConfiguration).image}

    def build_scoring_plan(self, request: ScoringRequest) -> ContainerScoringPlan:
        configuration = self.parse_configuration_as(request.configuration, ExampleConfiguration)
        run_inputs = self.parse_run_inputs_as(request.run_inputs, ExampleRunInputs)
        layout, resolve = request.layout, request.resolver.resolve
        weights = layout.model_resource_file(request.model_id, "examplenet.weights.bin")
        genome = layout.genome_fasta(request.genome_label)
        variants = layout.model_variants_file(request.job_id, request.model_id, request.scoring_batch)
        result = layout.scoring_result_file(request.job_id, request.model_id, request.scoring_batch)
        return single_container_plan(
            self,
            request,
            kind="examplenet_scoring",
            image=configuration.image,
            command=[
                "examplenet",
                "score",
                "--weights",
                resolve(weights),
                "--genome",
                resolve(genome),
                "--variants",
                resolve(variants),
                "--output",
                resolve(result),
            ],
            resources=ResourceRequest(memory_gb=4),
            inputs=[
                resource_transfer(configuration.weights, weights, locality_key=request.model_id),
                resource_transfer(run_inputs.genome, genome),
            ],
        )

What each part does:

  • model_type is the registry name, and the name a run spec uses.
  • default_output is the output selection a run uses unless it names another. The inherited validate_output_selection() accepts only this one; override it to accept others.
  • prioritize_predicate() is the rule that flags a variant. It is built from altar.predicates, so it runs in Python and in SQL. The per-model prioritized flag treats an unknown result as False.
  • scoring_runtime_identities() returns the exact runtime the plan uses for each runtime role. The image is part of the score identity.
  • build_scoring_plan() validates the request and returns the plan. The request's layout names every file by a logical path, such as models/<model_id>/examplenet.weights.bin. The request's resolver turns a logical path into the path the container sees.

single_container_plan() builds a plan of one task per batch, and checks it:

  • inputs lists the resources the task reads. resource_transfer() builds each one from a configured resource, keeping its URI and digest, so the backend can check the bytes it stages.
  • It adds the batch's variant file as an input, and the primary result file as an output. It adds one more output for each detail schema in the manifest, and one for each artifact the request selects.
  • command must name the resolved path of the variant file and of every result file, each as one argument. Otherwise it raises ValueError before a plan exists, because the task would read or write files the plan never stages or collects.
  • image must be the image scoring_runtime_identities() returns for the container role. The plan's identity is built from those identities and the request.
  • It labels the task with job_id, model_id, kind and the batch. Pass the binding's own labels in labels.

Name model files with layout.model_resource_file(model_id, basename). Choose the basename from the configuration, never from a resource URI's suffix: a content-addressed URI need not have an extension. A binding that runs several tasks per batch, such as one per fold and a summary task, builds a ContainerScoringPlan itself; the Cherimoya binding is an example. It then builds the plan's identity with self.scoring_run_identity(self.scoring_runtime_identities(configuration), configuration=configuration, output=output, run_inputs=run_inputs).

Result identity lists what the plan's identity records and leaves out. scoring_lineage_descriptor_for(request) derives the same identity's lineage without building the plan.

Keep the module light. Don't import Docker, Kubernetes, Modal or a model framework in it. Ship the model's command-line tool and its locked dependencies as a separate runtime project with its own image.

4. The files the runtime reads and writes

The container reads one variant file and writes one result file per batch.

The variant file

The variant file is a headerless, tab-separated UTF-8 file with one variant per line. Its five columns are the chromosome, the 1-based position, REF, ALT and the canonical variant ID:

chr1    3   G   C   chr1:3:G:C
chr1    9   A   T   chr1:9:A:T

prepare_scoring_batches() writes it for each batch, at layout.model_variants_file(job_id, model_id, batch). Every line is a distinct, eligible variant, in candidate order, with a canonical chromosome name such as chr1. A runtime reads it with altar_identity.read_variants(), which returns one VariantKey per line. The reader accepts a file without the fifth column, so a hand-written file of four columns works too. altar-identity is a small library with no dependencies, so a runtime image can install it on its own.

The result file

scoring_result_codec() returns the codec, the object that decodes the result file into rows. The default one reads a headered, tab-separated file with a variant_id column plus exactly the manifest's field names. An empty field is a missing value, which is stored as null:

variant_id  effect
chr1:3:G:C  0.75
chr1:9:A:T

Write one row per variant of the batch. A row for a variant outside the batch is an error, and the engine counts and logs batch variants without a row. Override scoring_result_codec() only when the runtime's columns differ:

from altar.scoring import DelimitedResultCodec

from altar_examplenet.plugin import ExamplePlugin


class NativeNamesExamplePlugin(ExamplePlugin):
    def scoring_result_codec(self) -> DelimitedResultCodec:
        return DelimitedResultCodec(
            self.manifest.result_schema,
            source_names={"effect": "native_delta"},
            allowed_extra_fields=("transport_only",),
        )

source_names renames runtime columns, never their meaning. allowed_extra_fields lists the columns the codec ignores. Any other unexpected column is an error. row_identity_fields keeps typed identity columns a store needs. The codec reads in bounded batches, and the engine validates every decoded row again before it calls the store. Don't write chr, pos, ref and alt columns for a store's sake: the engine derives them from variant_id.

Detail and artifact files

When the runtime also writes repeated observations, such as one row per track, declare a DetailSchema in the manifest. single_container_plan then adds a file per detail table, at layout.detail_result_file(...), and the engine decodes it with detail_result_codec(name). The default detail codec reads the same headered format. Override it with DelimitedDetailResultCodec for native names.

A large matrix or track file is an artifact instead. Declare an ArtifactSchema with its name, version, media type and scope. A run produces it only when its output selection names it. single_container_plan then adds an output at layout.artifact_result_file(...), and its artifact_extensions argument gives the file suffix, such as {"profiles": ".npz"}. The engine checks the file exists, records its digest and stores it through the ArtifactStore without decoding it. See Choose a result shape.

A plan names which of its output files holds which result in result_files, a tuple of ContainerResultFiles. Each entry has a name and the logical paths of its files. The name is primary, a detail schema's name, or a selected artifact's name. single_container_plan fills this in. A binding that builds its own ContainerScoringPlan must classify every terminal output exactly once, by logical path:

from altar.models import ContainerResultFiles, ContainerScoringPlan

plan = ContainerScoringPlan(
    shards=[score_task],
    summarize=summarize_task,
    ready_when=1,
    plugin_identity=identity,
    result_files=(
        ContainerResultFiles("primary", ("jobs/J/results/M/scores.tsv",)),
        ContainerResultFiles("splice_events", ("jobs/J/results/M/splice-events.tsv",)),
    ),
)

A plan whose manifest declares no details and whose run selects no artifact may leave result_files empty. Every terminal output is then a primary result file. The engine checks the classification before it launches any task, then routes each decoded batch to the ScoreStore or the DetailStore.

5. Build a scoring request

A ScoringRequest is one model instance scoring one batch: everything build_scoring_plan() reads. Tests build one by hand. Start tests/test_examplenet.py with a helper that builds one:

from altar.execution import PathResolver
from altar.models import ResourceReference, ScoringRequest

from altar_examplenet.plugin import ExampleConfiguration, ExamplePlugin, ExampleRunInputs

IMAGE = "ghcr.io/example/examplenet@sha256:" + "1" * 64


def example_request(weights: ResourceReference, genome: ResourceReference, resolver: PathResolver) -> ScoringRequest:
    return ScoringRequest(
        job_id="job-1",
        model_id="examplenet-hepg2",
        configuration=ExampleConfiguration(weights=weights, image=IMAGE),
        run_inputs=ExampleRunInputs(genome_build="hg38", genome=genome),
        output=ExamplePlugin.default_output,
        resolver=resolver,
    )

The fields:

  • job_id names the run's working files. It is not part of any identity.
  • model_id names the model instance in the stores: scores are read back by it.
  • configuration, run_inputs and output are the validated models from steps 2 and 3.
  • resolver is the execution backend's path_resolver(). PathResolver("/mnt/volume") matches the local, Kubernetes and Modal backends.
  • layout defaults to ScoringLayout().
  • scoring_batch and scoring_batch_count identify one batch. Leave them out of a template: prepare_scoring_batches() sets them on each request it returns.

6. Register the entry point

altar run and altar models find a binding through an entry point in the altar.model_plugins group. The key must equal model_type. A minimal pyproject.toml:

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "altar-examplenet"
version = "1.0.0"
dependencies = ["altar"]

[project.entry-points."altar.model_plugins"]
EXAMPLE = "altar_examplenet.plugin:ExamplePlugin"

[tool.pytest.ini_options]
asyncio_mode = "auto"

Install the package with pip install -e ., then check that altar models lists EXAMPLE. Package and register a plugin covers the other groups and the checks the registry runs.

7. Test with the conformance suites

altar.testing has a conformance suite for each part of a binding. Add three to tests/test_examplenet.py:

import pytest

from altar.models import ModelPlugin, get_model_plugin_registry
from altar.testing import ContainerScorerContract, ModelResultContract, PluginDiscoveryContract

PLACEHOLDER_WEIGHTS = ResourceReference(uri="gs://example-models/examplenet.bin", digest="sha256:" + "a" * 64)
PLACEHOLDER_GENOME = ResourceReference(uri="gs://example-genomes/hg38.fa", digest="sha256:" + "b" * 64)


class TestExampleResults(ModelResultContract):
    @pytest.fixture
    def plugin(self) -> ExamplePlugin:
        return ExamplePlugin()


class TestExampleContainerPlan(ContainerScorerContract):
    @pytest.fixture
    def plugin(self) -> ExamplePlugin:
        return ExamplePlugin()

    @pytest.fixture
    def scoring_request(self) -> ScoringRequest:
        return example_request(PLACEHOLDER_WEIGHTS, PLACEHOLDER_GENOME, PathResolver("/mnt/volume"))


class TestExampleDiscovery(PluginDiscoveryContract):
    @pytest.fixture
    def registry(self):
        return get_model_plugin_registry()

    @pytest.fixture
    def plugin_name(self) -> str:
        return "EXAMPLE"

    @pytest.fixture
    def expected_type(self) -> type[ModelPlugin]:
        return ModelPlugin

What the suites check:

  • ModelResultContract checks the manifest against the score columns, the configuration and run-input schemas, the prioritization predicate in Python and SQL, how results are assembled, and the eligibility declaration.
  • ContainerScorerContract checks the plan: task labels, resources, transfers, classified result files, serialization, and that the genome is part of the identity. It also checks that a saved request rebuilds the same plan.
  • PluginDiscoveryContract checks the installed entry point: Altar lists it without importing the module, and loading it returns a valid plugin. Run it after pip install -e ..

Also test what the suites can't know: the exact task command, native result decoding, missing values and the pinned default image. Keep real image and GPU runs out of the unit tests.

8. Run it end to end

altar.testing.InProcessExecutionBackend runs a plan's tasks by calling a Python function instead of the container. The function stands in for the runtime: it receives the task's ContainerTaskSpec, reads the files its command names and writes the result. Add a stand-in for examplenet score to tests/test_examplenet.py:

import argparse

from altar.execution import ContainerTaskSpec
from altar_identity import read_variants


def examplenet_runtime(spec: ContainerTaskSpec) -> int:
    """Stand in for the image's `examplenet score`: give every variant an effect of 0.75."""
    parser = argparse.ArgumentParser(prog="examplenet score")
    for option in ("--weights", "--genome", "--variants", "--output"):
        parser.add_argument(option, required=True)
    arguments = parser.parse_args(spec.command[2:])
    with open(arguments.output, "w") as output:
        output.write("variant_id\teffect\n")
        for key in read_variants(arguments.variants):
            output.write(f"{key.variant_id}\t0.75\n")
    return 0

The backend's directory, data_root, stands in for the volume a container mounts. Build the request with its path_resolver(), so the command names real files there. The backend copies each input into data_root and checks its digest, as a real backend does, so give the request real files. Then score a candidate file the way altar run does, with prepare_scoring_batches() and run_scoring():

from pathlib import Path

from altar.execution import LocalStorage, Transfer
from altar.models import sha256_file
from altar.results import SqliteScoreStore
from altar.scoring import prepare_scoring_batches, run_scoring
from altar.testing import InProcessExecutionBackend


def local_resource(path: Path) -> ResourceReference:
    return ResourceReference(uri=str(path), digest=sha256_file(path))


async def test_examplenet_scores_end_to_end(tmp_path: Path) -> None:
    weights = tmp_path / "examplenet.weights.bin"
    weights.write_bytes(b"synthetic weights")
    genome = tmp_path / "hg38.fa"
    genome.write_text(">chr1\nACGTACGTAC\n")
    candidates = tmp_path / "candidates.tsv"
    candidates.write_text("chr1\t3\tG\tC\nchr1\t5\tA\tAT\n")

    plugin = ExamplePlugin()
    backend = InProcessExecutionBackend(examplenet_runtime, data_root=tmp_path / "volume")
    template = example_request(local_resource(weights), local_resource(genome), backend.path_resolver())
    store = SqliteScoreStore(str(tmp_path / "scores.sqlite"))

    async def prepare():
        return await prepare_scoring_batches(
            plugin,
            template,
            candidate_variants=Transfer(uri=str(candidates), logical_path="candidates.tsv"),
            score_store=store,
            storage=LocalStorage(),
            destination_transfer=backend.on_data_root,
            max_variants_per_batch=1000,
        )

    preparation = await prepare()
    assert preparation.ineligible_count == 1  # ExampleNet scores SNVs only, so the insertion is set aside.
    for batch in preparation.batches:
        result = await run_scoring(
            plugin,
            batch.request,
            model_name="ExampleNet",
            score_store=store,
            backend=backend,
            storage=LocalStorage(),
            input_transfer=backend.on_data_root,
            output_transfer=backend.on_data_root,
            poll_interval_s=0.01,
        )
        assert result.added == 1

    assert await store.read_score("examplenet-hepg2", "chr1:3:G:C") == {"effect": 0.75}
    assert (await prepare()).batches == ()  # the next preparation finds the score in the cache
    store.close()

prepare_scoring_batches() writes each batch's variant file through destination_transfer, and returns a request per batch. backend.on_data_root puts the variant file and the result files under data_root, and leaves resources at their own URIs. run_scoring() stages the inputs, runs the task, decodes the result file, and stores the rows. A binding with detail tables also passes a detail_store, such as altar.testing.InMemoryDetailStore, as Add an inline model binding shows.

The stand-in runtime doesn't prove the model computes the right numbers. It proves the binding's plan, command, file formats and codec fit Altar's scoring path. Test the runtime itself, and compare it with the model's published results, in the runtime project.

Going further

Prioritization that reads annotations

A prioritization rule can read annotation columns as well as scores, such as a region type. Declare each one in the manifest's PrioritizationPolicy as an AnnotationDependency: the contract's source_id, the lowest schema_version the rule accepts, and the columns it reads. When Altar assembles each variant's result, it checks the dependency against the configured sources before it evaluates the rule. Annotation dependencies describes how it resolves them, and What prioritized means describes what a reader sees.

Saved configurations

plugin.configuration_schema() and plugin.run_input_schema() return JSON Schema, so a caller can render help without importing a model framework. save_configuration() attaches the plugin, schema and version identity, and load_configuration() checks it. Override migrate_configuration() when a later schema version needs an explicit migration. Implement convert_legacy_artifact() only for the exact legacy shape you support, and reject unknown keys.

Reuse scores across releases

A new plugin_version or image starts a new score lineage. When two releases compute the same scores, override equivalence_projection() and equivalence_rules() to declare which lineages are equal, and list the releases it bridges in equivalence_version_bridges. Equivalent lineages describes the rules a projection must keep.

Preparation

Altar does not train models: name the trained weights and other resources in the configuration. A model that derives reusable files from them before scoring implements build_preprocessing_plan(), which returns a ModelWorkflowPlan whose operation is "preparation". PreprocessingRequest carries no layout: the binding chooses those paths. altar prepare runs it; see Prepare model resources.

The plan uses named WorkflowStage values. Tasks in one stage run in parallel, and needs names the stages that must succeed first. Declare the terminal files in plan.outputs, then serialize the plan with workflow_plan_to_json() or run it with run_model_workflow().

A preparation step may write a manifest of what it produced. Scoring must not require that manifest unless the model needs it, so files prepared elsewhere stay valid inputs. A binding that checks published files when it scores overrides the provisional prepared_run_inputs(), which altar run calls for each model whose files altar prepare published.

Ready when

  • The manifest has a unique plugin_id, a plugin_version, an altar_api range that includes ALTAR_API_VERSION, and a result schema whose every field states its units, direction and meaning.
  • Every setting that changes scores is a field of the configuration, and every resource is a ResourceReference with a SHA-256 digest.
  • scoring_runtime_identities() returns the exact image digest or service identity the plan uses.
  • The package imports without the model framework, weights, a GPU or credentials.
  • The entry point's key equals model_type, and altar models lists it after pip install -e ..
  • PluginDiscoveryContract, ModelResultContract, and ContainerScorerContract or InlineScorerContract pass.
  • One test scores a candidate file through prepare_scoring_batches() and run_scoring().
  • The runtime project compares its scores with the model's published results.
  • The model's page documents its score fields, inputs, resources, validation, citation and licence. Write an integration page gives the template and its generator.

Next