Skip to content

Add an inline model binding

An inline model binding scores variants in the Python process that calls Altar, in its execute_inline() method, instead of in a container. Use it for a model served by a hosted API, or for a scorer light enough to run beside Altar. It declares its manifest and configuration as a container binding does, and needs no execution backend.

When to choose an inline binding

Write an inline binding when the model needs no container: a hosted API computes the scores, or a small Python scorer does. A model that needs TensorFlow, PyTorch, weights or a GPU is a container binding; see Add a model binding.

The steps below build InlineNet, which calls a hosted API that returns an effect per track. It stores the strongest track as the primary row and every track in a detail table. Read steps 1 and 2 of Add a model binding first: the manifest and configuration work the same way, and this page shows only what differs. The code goes in the same package, as altar_examplenet/inline.py, with its tests in tests/test_inlinenet.py. Altar's own test suite runs this page's code as written.

The interface

An inline binding subclasses ModelPlugin, with the members every binding sets (The interface), plus these:

Member Required? What it is
build_scoring_plan(request) required Returns an InlineScoringPlan: an executor name and a JSON payload.
execute_inline(plan, runtime) required Computes the rows of an inline plan.
with_run_variants(request, variants) required Puts one batch's variants into a request's run inputs.
run_variant_ids(run_inputs) provisional; default None Reads those 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.

A provisional member is expected to change; see Provisional names.

1. Write the plugin

Put InlineNet in altar_examplenet/inline.py:

from collections.abc import Callable, Sequence
from dataclasses import replace

from altar.models import (
    ApiVersionRange,
    DetailSchema,
    InlineScoringPlan,
    ModelConfiguration,
    ModelPlugin,
    ModelRunInputs,
    OutputSelection,
    PluginCapability,
    PluginKind,
    PluginManifest,
    PrioritizationPolicy,
    ResultField,
    ResultSchema,
    RuntimeContext,
    RuntimeIdentityPolicy,
    RuntimeKind,
    RuntimeRequirement,
    ScoringRequest,
    VariantKey,
)
from altar.predicates import Abs, Col, Ge, Lit, Predicate
from altar.scoring import DetailResultBatch, InlineScoringResult

INLINENET_API = "inlinenet-api:v1"

TRACK_EFFECTS = DetailSchema(
    name="track_effects",
    version="1.0.0",
    description="InlineNet's predicted effect on every requested track",
    fields=(
        ResultField("track", "str", "Track", "Assay and cell type of the predicted track", nullable=False),
        ResultField("effect", "float", "Effect", "Alternate-minus-reference predicted signal"),
    ),
    key_fields=("track",),
    row_count_field="n_tracks",
)

INLINENET_MANIFEST = PluginManifest(
    plugin_id="org.example.inlinenet.model",
    kind=PluginKind.MODEL,
    capabilities=frozenset({PluginCapability.SCORE, PluginCapability.MATERIALIZE_RESULTS}),
    architecture="InlineNet",
    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("top_track", "str", "Top track", "Track with the largest absolute effect"),
            ResultField("top_effect", "float", "Top effect", "Effect on the top track"),
            ResultField("n_tracks", "int", "Tracks", "Track effects returned for the variant"),
        ),
    ),
    detail_schemas=(TRACK_EFFECTS,),
    prioritization=PrioritizationPolicy("inlinenet-top-effect", "1.0.0"),
    runtimes=(
        RuntimeRequirement(
            name="model_api",
            kind=RuntimeKind.EXTERNAL_SERVICE,
            policy=RuntimeIdentityPolicy.DECLARED_EXACT,
            declared_identity=INLINENET_API,
        ),
    ),
)

Predict = Callable[[str, tuple[str, ...]], dict[str, float]]


class InlineNetConfiguration(ModelConfiguration):
    tracks: tuple[str, ...] = ("DNase:HepG2", "CAGE:liver")


class InlineNetRunInputs(ModelRunInputs):
    variant_ids: tuple[str, ...] = ()


class InlineNetRuntime(RuntimeContext):
    """The API client. It is supplied at run time and never saved."""

    __slots__ = ("predict",)

    def __init__(self, predict: Predict) -> None:
        self.predict = predict


class InlineNetPlugin(ModelPlugin):
    model_type = "INLINENET"
    manifest = INLINENET_MANIFEST
    configuration_schema_id = "org.example.inlinenet.model.configuration"
    configuration_model = InlineNetConfiguration
    run_input_model = InlineNetRunInputs
    default_output = OutputSelection(reducer="max_abs_track_v1")
    reads_reference_genome = False

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

    def build_scoring_plan(self, request: ScoringRequest) -> InlineScoringPlan:
        configuration = self.parse_configuration_as(request.configuration, InlineNetConfiguration)
        run_inputs = self.parse_run_inputs_as(request.run_inputs, InlineNetRunInputs)
        identity = self.scoring_run_identity(
            {"model_api": INLINENET_API},
            configuration=configuration,
            output=self.validate_output_selection(request.output),
            run_inputs=run_inputs,
        )
        payload = {"tracks": list(configuration.tracks), "variant_ids": list(run_inputs.variant_ids)}
        return InlineScoringPlan(plugin_identity=identity, executor="inlinenet.score", payload=payload)

    def with_run_variants(self, request: ScoringRequest, variants: Sequence[VariantKey]) -> ScoringRequest:
        run_inputs = self.parse_run_inputs_as(request.run_inputs, InlineNetRunInputs)
        variant_ids = [variant.variant_id for variant in variants]
        rebound = InlineNetRunInputs.model_validate({**run_inputs.to_dict(), "variant_ids": variant_ids})
        return replace(request, run_inputs=rebound)

    def run_variant_ids(self, run_inputs: ModelRunInputs) -> Sequence[str]:
        return self.parse_run_inputs_as(run_inputs, InlineNetRunInputs).variant_ids

    async def execute_inline(
        self, plan: InlineScoringPlan, runtime: RuntimeContext | None = None
    ) -> InlineScoringResult:
        if plan.executor != "inlinenet.score" or not isinstance(runtime, InlineNetRuntime):
            raise ValueError("an InlineNet plan runs with an InlineNetRuntime")
        primary, details = [], []
        for variant_id in plan.payload["variant_ids"]:
            effects = runtime.predict(variant_id, tuple(plan.payload["tracks"]))
            top = max(effects, key=lambda track: abs(effects[track]), default=None)
            primary.append(
                {
                    "variant_id": variant_id,
                    "top_track": top,
                    "top_effect": None if top is None else effects[top],
                    "n_tracks": len(effects),
                }
            )
            details.extend(
                {"variant_id": variant_id, "track": track, "effect": effect} for track, effect in effects.items()
            )
        return InlineScoringResult(
            primary_rows=tuple(primary),
            details=(DetailResultBatch(TRACK_EFFECTS.name, tuple(details)),),
        )

How it differs from a container binding:

  • The runtime role is an EXTERNAL_SERVICE with a DECLARED_EXACT identity. Change INLINENET_API when the service's model changes, because it is part of the score identity. An in-process scorer uses IN_PROCESS.
  • The service supplies its own sequence, so the plugin sets reads_reference_genome = False and its run inputs subclass ModelRunInputs. A reference a caller supplies changes neither its plans nor its identity.
  • The run inputs carry the variants to score. A container plan reads them from the staged variant file instead.
  • build_scoring_plan() returns an InlineScoringPlan: an executor name and a JSON payload. It must survive scoring_plan_to_json() and scoring_plan_from_json() across a process restart, so it holds no client and no function.
  • execute_inline() combines the plan with the RuntimeContext the caller supplies, here the API client. A RuntimeContext cannot be saved or serialized, and it never enters the identity.

2. Put each batch's variants into the request

prepare_scoring_batches() removes duplicates, ineligible variants and already-stored variants from a candidate file. It then calls with_run_variants(request, variants) once per batch, to put that batch's variants into a copy of the request. The copy may differ from the request only in its run inputs, and its plan must have the same identity: the variants are per-run biology, not part of the model instance. Preparation also calls it with an empty batch first. Without this method, preparing an inline binding raises CapabilityNotSupported, and InlineScorerContract fails.

run_variant_ids(run_inputs) reads those variants back. run_scoring() calls it for an inline plan. A primary or detail row for any other variant raises ScoringOutputError, and batch variants without a primary row are counted in ScoringRunResult.variants_without_rows. The default returns None, which skips both checks.

3. Return primary and detail rows

execute_inline() returns either a list of primary rows or an InlineScoringResult. The result holds the primary rows, one DetailResultBatch per detail table in the manifest, and the artifacts the request selects:

  • Each primary row has variant_id plus the manifest's fields.
  • Each detail row has variant_id plus the detail schema's fields.
  • row_count_field names the primary field that counts a variant's detail rows, and the engine checks that count. A stored variant whose count is 0 is complete, so it is not scored again for lack of detail rows.

The engine writes the details before the primary rows, so a run that fails in between leaves the variant unscored. Choose a result shape says when an output is a detail table.

4. Register the entry point

Register InlineNet in the altar.model_plugins group, under its model_type, beside ExampleNet in the pyproject.toml of step 6:

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

5. Test it and run it end to end

InlineScorerContract replaces the container binding's ContainerScorerContract. Its inline_runtime fixture supplies the client. Put this in tests/test_inlinenet.py:

from dataclasses import replace
from pathlib import Path

import pytest

from altar.execution import LocalStorage, PathResolver, Transfer
from altar.models import ScoringRequest
from altar.results import SqliteScoreStore
from altar.scoring import prepare_scoring_batches, run_scoring
from altar.testing import InlineScorerContract, InMemoryDetailStore, ModelResultContract
from altar_examplenet.inline import InlineNetConfiguration, InlineNetPlugin, InlineNetRunInputs, InlineNetRuntime


def fake_predict(variant_id: str, tracks: tuple[str, ...]) -> dict[str, float]:
    """Stand in for the InlineNet API."""
    return {track: 0.8 if index == 0 else -0.2 for index, track in enumerate(tracks)}


def inline_request(*variant_ids: str) -> ScoringRequest:
    return ScoringRequest(
        job_id="job-1",
        model_id="inlinenet-v1",
        configuration=InlineNetConfiguration(),
        run_inputs=InlineNetRunInputs(genome_build="hg38", variant_ids=variant_ids),
        output=InlineNetPlugin.default_output,
        resolver=PathResolver(),
    )


class TestInlineNetResults(ModelResultContract):
    @pytest.fixture
    def plugin(self) -> InlineNetPlugin:
        return InlineNetPlugin()


class TestInlineNetScorer(InlineScorerContract):
    @pytest.fixture
    def plugin(self) -> InlineNetPlugin:
        return InlineNetPlugin()

    @pytest.fixture
    def scoring_request(self) -> ScoringRequest:
        return inline_request("chr1:100:A:C", "chr2:200:G:T")

    @pytest.fixture
    def inline_runtime(self) -> InlineNetRuntime:
        return InlineNetRuntime(fake_predict)


async def test_inlinenet_scores_end_to_end(tmp_path: Path) -> None:
    candidates = tmp_path / "candidates.tsv"
    candidates.write_text("chr1\t100\tA\tC\nchr2\t200\tG\tT\n")
    plugin, store, details = InlineNetPlugin(), SqliteScoreStore(), InMemoryDetailStore()

    preparation = await prepare_scoring_batches(
        plugin,
        inline_request(),
        candidate_variants=Transfer(uri=str(candidates), logical_path="candidates.tsv"),
        score_store=store,
        detail_store=details,
        storage=LocalStorage(),
        destination_transfer=lambda transfer: replace(transfer, uri=str(tmp_path / transfer.logical_path)),
        max_variants_per_batch=1000,
    )
    for batch in preparation.batches:
        await run_scoring(
            plugin,
            batch.request,
            model_name="InlineNet",
            score_store=store,
            detail_store=details,
            runtime=InlineNetRuntime(fake_predict),
        )

    assert await store.read_score("inlinenet-v1", "chr1:100:A:C") == {
        "top_track": "DNase:HepG2",
        "top_effect": 0.8,
        "n_tracks": 2,
    }
    rows = [row async for row in details.read_rows(model_id="inlinenet-v1", detail_name="track_effects")]
    assert len(rows) == 4
    store.close()
  • ModelResultContract checks the manifest, the schemas, the prioritization rule and how results are assembled, as for a container binding.
  • InlineScorerContract checks the plan and its serialization, the rows execute_inline() returns, and that with_run_variants() changes only the run inputs and keeps the plan's identity.
  • The end-to-end test scores a candidate file through prepare_scoring_batches() and run_scoring(), with a fake client standing in for the API.

An inline run needs no backend or storage. prepare_scoring_batches() binds each batch into a request through with_run_variants(), and destination_transfer only says where to write the report of ineligible variants. Add a PluginDiscoveryContract for INLINENET, as in step 7.

Ready when

  • The manifest declares the service's runtime role with a DECLARED_EXACT identity, or an IN_PROCESS one.
  • The plan's payload is plain JSON, and the client reaches execute_inline() only through a RuntimeContext.
  • with_run_variants() changes only the run inputs, and run_variant_ids() reads them back.
  • PluginDiscoveryContract, ModelResultContract and InlineScorerContract pass.
  • One test scores a candidate file through prepare_scoring_batches() and run_scoring().
  • The rest of the model binding checklist holds.

Next