Solution Variants

The combiner produces a single continuous total score per link. Each solution variant is one way of rendering that scalar into a verdict shape — the scoring is shared; the only thing that differs is how the threshold(s) are placed and what the output looks like.

Keeping the variants as siblings makes it cheap to add new ones and honest about the fact that the interesting question (“what decision do we make?”) is not the same as the interesting question (“how confident are we?”).

Current catalog

• solution-match — binary verdict: Match / Mismatch. The one the prompt asks for.
• solution-triage — three-tier verdict: Match / Review / Mismatch. Recovers F&S’s A₂ possible link decision by banding the same total score.
• solution-splink — probabilistic verdict via the splink library. Optional dep, lazy-imported. The F&S port our hand-tuned variants approximate.

Shared machinery

All variants call the same mercury.match.evaluate function, which produces a LinkResult with per-field scores and a total. See scoring-combiner for the scalar construction, and matching-approach for the theoretical framing.

Adding a new variant

To add a solution variant:

1. Add a new CLI subcommand in src/mercury/cli.py that loads the inputs with the shared _score_all helper and formats the output.
2. Put any variant-specific classifier function in src/mercury/match.py (see classify_tier for the pattern).
3. Add an end-to-end anchor test at tests/test_solution_<name>.py asserting the full printed output against the 9-link fixtures.
4. Write a reference card at docs/reference/solution-<name>.md and link it from this index.
5. If the variant reflects a new way of thinking about the decision problem (rather than just a different threshold), add an explanation in alternative-solutions.