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_idis a globally unique, reverse-domain name for the binding.plugin_versionis the binding's release.altar_apiis 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 withaltar.models.ALTAR_API_VERSION, which is0.1.0. That number is the version of the plugin interface, not of thealtarpackage, 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_versionand the result schema'sversiondescribe saved formats.result_schemalists the primary result columns. Give each field its units, direction, nullability and biological meaning. It is the only column declaration: the inheritedscore_columns()is derived from it.prioritizationnames and versions the rule that flags a variant, which step 3 defines.runtimesnames the runtime roles.DIGEST_REQUIREDaccepts only an immutablename@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_buildis the assembly of the run's variants, such ashg38.GRCh38is accepted and stored ashg38. It is the build the run's scores are stored under.genomeis the reference FASTA, as aResourceReferencethat must carry a digest. Its digest is part of the run's identity. The plan stages it atlayout.genome_fasta(genome_build), which isgenomes/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_typeis the registry name, and the name a run spec uses.default_outputis the output selection a run uses unless it names another. The inheritedvalidate_output_selection()accepts only this one; override it to accept others.prioritize_predicate()is the rule that flags a variant. It is built fromaltar.predicates, so it runs in Python and in SQL. The per-modelprioritizedflag treats an unknown result asFalse.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'slayoutnames every file by a logical path, such asmodels/<model_id>/examplenet.weights.bin. The request'sresolverturns a logical path into the path the container sees.
single_container_plan() builds a plan of one task per batch, and checks it:
inputslists 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.
commandmust name the resolved path of the variant file and of every result file, each as one argument. Otherwise it raisesValueErrorbefore a plan exists, because the task would read or write files the plan never stages or collects.imagemust be the imagescoring_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,kindand the batch. Pass the binding's own labels inlabels.
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:
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:
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_idnames the run's working files. It is not part of any identity.model_idnames the model instance in the stores: scores are read back by it.configuration,run_inputsandoutputare the validated models from steps 2 and 3.resolveris the execution backend'spath_resolver().PathResolver("/mnt/volume")matches the local, Kubernetes and Modal backends.layoutdefaults toScoringLayout().scoring_batchandscoring_batch_countidentify 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:
ModelResultContractchecks 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.ContainerScorerContractchecks 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.PluginDiscoveryContractchecks the installed entry point: Altar lists it without importing the module, and loading it returns a valid plugin. Run it afterpip 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, aplugin_version, analtar_apirange that includesALTAR_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
ResourceReferencewith 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, andaltar modelslists it afterpip install -e .. PluginDiscoveryContract,ModelResultContract, andContainerScorerContractorInlineScorerContractpass.- One test scores a candidate file through
prepare_scoring_batches()andrun_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¶
- Add an inline model binding builds a binding that calls a hosted API.
- Add interpretation to a model binding declares methods that explain the model's predictions.
- Package and register a plugin covers the manifest, result identity and versioning rules.