Add CachedPredictor — predictions-as-data core (part 1 of #128)

[iskandr]

Summary

First PR implementing #128 (pluggable prediction sources). Ships the `CachedPredictor` class, the core `(prediction_method_name, predictor_version)` invariant, fallback semantics, and four loaders. Does not include sharding (`concat` / `from_directory`) or the NetMHCpan .xls parser — separate follow-up PRs.

No version bump, no PyPI release: the feature lands across multiple PRs; release once #128 is substantially complete.

What's in

• `topiary/cached.py` — `CachedPredictor` class. Implements the mhctools predictor protocol (`predict_peptides_dataframe`, `predict_proteins_dataframe`, `alleles`, `default_peptide_lengths`) by looking up rows in a normalized DataFrame keyed on `(peptide, allele, peptide_length)`.
• Core invariant: a single cache holds predictions from exactly one `(prediction_method_name, predictor_version)` pair. Enforced at construction (mixed rows → `ValueError`) and on first fallback call (lazy version-check against the fallback's output).
• Fallback: `fallback=None` → miss raises `KeyError` with missed peptides listed. `fallback=` → miss delegates and the result is merged back into the cache. No `populate_on_miss` flag — caching fallback hits is always the right default.
• Loaders: `from_dataframe`, `from_topiary_output` (Parquet / TSV), `from_tsv` (generic w/ column mapping), `from_mhcflurry` (maps `mhcflurry_*` columns onto canonical names).
• `save(path)` round-trip for Parquet / TSV / CSV so caches persist across sessions.
• `topiary.CachedPredictor` exported at the top level.

What's deferred

• `from_netmhcpan` (.xls parsing — both Class-I and Class-II formats)
• `concat([...])`, `from_directory(...)`, overlap-resolution policy
• CHANGELOG entry (deferred to the release-prep PR when Pluggable prediction sources — external formats, topiary round-trip, sharded caches #128 lands in full)

Test plan

• `python -m pytest tests/test_cached_predictor.py` — 23 passed
• `./test.sh` — 1075 passed, 3 skipped (up from 1052)
• `./lint.sh` — clean
• CI green

Part 1 of #128.

[coveralls]

coverage: 88.297% (+0.2%) from 88.127% — add-cached-predictor into master

[iskandr]

Vaxrank-consumer review

Reading from vaxrank 2.1.2's angle — this lands on a real vaxrank pain point I hadn't explicitly asked for in #121: vaxrank calls predict_from_named_sequences twice per mutation (mutant + WT), and the two share most of their sliding-window 9-mers. A CachedPredictor(fallback=mhc_predictor) persisted across a vaxrank run collapses those duplicate queries end-to-end — this is a bigger win than the straight WT-pass (topiary#123) on realistic inputs.

Design calls I like

• Single (name, version) invariant, enforced at construction and lazily on fallback attach. ValueError with full multi-pair listing is exactly the diagnostic I'd want.
• also_accept_versions as opt-in, not auto-bypass. Upgrading a predictor across a patch release is semantically risky; forcing the caller to name the specific accepted version captures intent without a silent trap.
• mhcflurry_composite_version() composing pkg + model-release is the right granularity. The auto-compose on from_mhcflurry(..., predictor_version=None) means users never hand-enumerate bundles.
• TopiaryPredictor(models=cache) singular form (line test_cache_as_model_predict_from_sequences) — nice to see; matches what I'd asked for on Refactor predict_from_variants onto AntigenFragment (PR B) #121. Is single-model auto-wrapping now always supported, or just when the arg is a cache?

Concerns / suggestions

1. Partial-allele coverage over-queries the fallback. In predict_peptides_dataframe the miss-detection is at peptide granularity: if peptide P1 has cache hits for allele A but is missing for allele B, the whole P1 gets sent to fallback.predict_peptides_dataframe([P1]). The fallback typically predicts across all its alleles, so (P1, A) gets re-predicted and merged back, overwriting the cached row with the fallback's output. Correct, but wasteful if the caller's cache was partial-on-purpose. Worth either (a) documenting "fallback results overwrite overlapping cache rows" or (b) filtering the fallback output to only the actually-missed (peptide, allele) pairs before merging. Vaxrank usage probably has uniform allele coverage so won't hit this, but doc is cheap.

2. peptide_length lock-in is invisible. A cache built from only 9-mers has default_peptide_lengths == [9]; predict_proteins_dataframe will silently slide 9-mers only, dropping 8/10/11 windows. For a cache backed by a fallback that supports more lengths this is fine, but a cache used standalone can silently under-return. Worth a docstring note on default_peptide_lengths — or, if the cache has a fallback, maybe union the fallback's lengths on empty-cache to avoid surprises (which is what you're already doing — good; just make that explicit in the protein-path doc).

3. _index as dict-of-dicts has O(rows) Python-object overhead. Fine for vaxrank (thousands of peptides per run); but whole-proteome caches (millions of rows, which I'd expect some topiary consumers to build) will feel it. A row-index lookup into the DataFrame, or a MultiIndex, would be more memory-efficient. Not blocking — flag for a follow-up benchmark.

4. Thread safety. _fallback_resolve mutates self._df and self._index without locking. Two threads concurrently missing the same peptide would both call the fallback and race on the merge. Vaxrank is single-threaded, so no blocker — but a one-line docstring note ("not thread-safe; wrap in a lock if shared across workers") would save a future bug report.

5. Pristine empty cache + save() edge case. CachedPredictor(fallback=X) (empty _df, prediction_method_name=None) lets you save before any queries run. The resulting TSV/Parquet has the schema columns but no rows, and reloading via from_topiary_output would hit _unique_version_pair with empty pairs → ValueError("empty DataFrame"). So roundtripping a never-queried cache breaks. Minor, and probably not a real use case, but either error-early in save() when identity is unset or document "save a populated cache only."

6. mhctools protocol shape. predict_dataframe = predict_peptides_dataframe — nice compat alias. Worth checking whether downstream code paths in topiary's own TopiaryPredictor._predict_raw* use the positional-arg vs keyword-arg shape consistently; I noticed vaxrank wraps bare mhctools predictors on every call (TopiaryPredictor(models=[mhc_predictor]) in epitope_logic.py) rather than keeping a long-lived predictor. A CachedPredictor wrapping that bare predictor plus persistence across calls would be the idiomatic fix on the vaxrank side.

Vaxrank follow-up sketch (for my own tracking)

Once this lands:

• One CachedPredictor(fallback=mhc_predictor, save_path=...) per vaxrank run, shared across the mutant + WT predict_from_named_sequences calls.
• Combined with topiary#123 (predict_wt=True), the ~40 lines of WT plumbing in vaxrank/epitope_logic.py:120–161 collapse to a single call with both directions cached.
• The predictor_version stamping gives users a natural reproducibility artifact (current vaxrank has none).

Overall: this is a well-scoped part 1. Ship it; the concerns above are mostly docs/edge cases.