pyhighlights

Select-then-predict models for highlight-based explainable AI research.

Most explainability methods answer why did the model say that? after the fact, and nothing forces the answer to be true. A select-then-predict model rearranges the pipeline so the question does not arise: a selector picks a subset of the input, and a predictor sees only that subset. The selected subset — the highlight — is not a story about the prediction, it is the input to it. A highlight that omits what mattered produces a worse prediction, which is measurable rather than arguable.

Documentation · Tutorial · Contributing

Installation

pip install pyhighlights

Transformer backbones are an extra, so a GRU run does not pull in transformers:

pip install "pyhighlights[transformers]"

One key, one experiment

A task is one experiment start to finish — a corpus, its preprocessing, a model, its metrics, and a list of seeds:

from pathlib import Path

import pyhighlights
from cinnamon.registry import Registry
from pyhighlights.components.analyzers import MetricsAnalyzer, PredictionAnalyzer
from pyhighlights.configurations.keys import TOY_TASK

Registry.build(directory=Path(pyhighlights.__file__).parent)

task = Registry.from_key(
    TOY_TASK,
    save_path="results",
    seeds=[0, 1],
    store_predictions=True,
)
task.run()

Each seed trains from scratch, restores the checkpoint that scored best on validation, and is scored on validation and test. Seeds are a list rather than a number because one run of a select-then-predict model says very little: the selector is trained through a discrete choice, and the spread across seeds is part of the result.

What lands on disk:

results/toy/2026-09-09T17-55-22/
├── results.json               # every seed's metrics, and their summary
├── manifest.json              # the key, the overrides, the whole
│                              #   configuration tree, and the versions
├── predictions-seed=0.pkl
├── predictions-seed=1.pkl
└── seed=0/epoch=0-step=8.ckpt

A run never overwrites an earlier one: two runs of a task are two results to compare. The manifest names the key and the arguments the run was launched with, and resolves every nested key into the numbers behind it — so the file states the hidden size and the learning rate rather than the name of the place they came from.

Read the results back as frames, so the same analyzer serves a notebook, a test and a LaTeX table:

MetricsAnalyzer(directory="results", metrics=["accuracy", "highlight_f1"]).run()

task                 run  seeds          accuracy      highlight_f1
 toy 2026-09-09T17-55-22      2 0.4062 +/- 0.0312 0.0000 +/- 0.0000

A stored prediction is token ids and masks. PredictionAnalyzer rebuilds the corpus from the key in the manifest and joins on sample_id, so a row says which words the model kept:

PredictionAnalyzer(directory="results").analyze()[
    ["seed", "sample_id", "label", "predicted", "selected_text"]
]

What is in it

Architectures, each a different answer to selection being a discrete choice inside a differentiable model. All eight are registered for both a GRU and a Transformer backbone; the algorithms never mention either, because a backbone is anything implementing encode / pool / output_size.

Corpora, each loaded as its authors distributed it: R2A beer and hotel (three aspects each), ERASER movies, hatexplain, and a synthetic toy for smoke tests. Cleaning is a preprocessor a study names, not something a loader does, so two studies over one corpus can prepare it differently.

Metrics per corpus, by output classes and by highlights, plus faithfulness — sufficiency and comprehensiveness — over the test split.

Reproductions live in pyhighlights_benchmarks, beside the library rather than inside it, so nothing here carries one paper's values. GenSPP (ACL 2025) is the first: two corpora against the five architectures that paper compares — FR, MCD, MGR, G-RAT and GenSPP — rather than against all eight the library ships.

Where it is going

Roadmap — Zenodo dataset artifacts so a reproduction does not depend on a URL somebody else controls, a study on unannotated legal text, per-corpus sparsity targets, and the rest of the highlight-metric suite.

pyhighlights ships tools, not an experiment. Which metrics to log, which aspect of Beer to train on, which sparsity target to aim at — all of that depends on a study, so all of it stays a configuration the study writes.