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_SERVICEwith aDECLARED_EXACTidentity. ChangeINLINENET_APIwhen the service's model changes, because it is part of the score identity. An in-process scorer usesIN_PROCESS. - The service supplies its own sequence, so the plugin sets
reads_reference_genome = Falseand its run inputs subclassModelRunInputs. 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 anInlineScoringPlan: an executor name and a JSON payload. It must survivescoring_plan_to_json()andscoring_plan_from_json()across a process restart, so it holds no client and no function.execute_inline()combines the plan with theRuntimeContextthe caller supplies, here the API client. ARuntimeContextcannot 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_idplus the manifest's fields. - Each detail row has
variant_idplus the detail schema's fields. row_count_fieldnames 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()
ModelResultContractchecks the manifest, the schemas, the prioritization rule and how results are assembled, as for a container binding.InlineScorerContractchecks the plan and its serialization, the rowsexecute_inline()returns, and thatwith_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()andrun_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_EXACTidentity, or anIN_PROCESSone. - The plan's payload is plain JSON, and the client reaches
execute_inline()only through aRuntimeContext. with_run_variants()changes only the run inputs, andrun_variant_ids()reads them back.PluginDiscoveryContract,ModelResultContractandInlineScorerContractpass.- One test scores a candidate file through
prepare_scoring_batches()andrun_scoring(). - The rest of the model binding checklist holds.
Next¶
- Package and register a plugin covers the manifest, result identity and versioning rules.
- Validate an implementation lists every conformance suite.