Partial cache-backed prediction batches¶
Implementation specification for #304 and compatibility audit for #374.
The default remains strict: a missing peptide, context, kind or genotype raises
CachedPredictorCoverageError. Existing raise_on_error only controls variant
annotation and must not silently change prediction completeness.
An explicit TopiaryPredictor(cache_miss_handler=...) opts into retaining
successful model/input pairs. The handler receives a structured record for every
skipped pair, with input identity, model identity, prediction stage and original
error. Split only failed batches until the failing input is isolated. Skip the
entire sequence for that model, not just its missing window: this preserves
protein flanks and never substitutes an incompatible prediction. Other models
can still score that sequence. Whole-peptide, fragment, wildtype and self-nearest
prediction paths use the same policy; unexpected errors still propagate.
A public predict_with_cache_miss_report function supplies this shared policy.
The handler is the authoritative report across composed workflows; successful
rows remain ordinary prediction rows. Emit an explicit warning when any inputs
are skipped. Callers must retain the report alongside the partial table.
CLI --cache-miss-report PATH opts in, requires a real JSON file distinct from
inputs and prediction outputs, and writes a versioned completeness report before
writing the result table. Complete runs return 0; partial runs return 3, including
runs with zero successful predictions. CSV stdout remains parseable. The report
is written even if every cache lookup succeeds. No predictions are fabricated.
Tests must run strict and reporting modes on the same covered/uncovered inputs, assert successful sequences/models survive, keep repeated peptide contexts separate, preserve kind/genotype failure checks, exercise composed fragment/WT and CLI workflows, and prove unrelated exceptions and handler failures still raise. Fixture builders belong beside the tests.
Topiary 5.68.4 (#380) now delegates fixture resolution and generation to the
published Osteosarc 0.2.3 fixture_assets and consumer_fixtures APIs. Osteosarc
0.1.4 lacks these APIs and is no longer a compatible development baseline.
Topiary requires one osteosarc minor series at a time (see requirements.txt),
accepting patch fixes within it. Verify shared fixtures offline, built-distribution
metadata, normal dependency resolution and an editable installation. Shared source data and historical scientific expectations stay
pinned independently of the package version.