Add retrieval example suite for recall@k, MRR and nDCG

[HarshRajSinghania]

Summary

Adds an offline retrieval example that exercises the retrieval scorers end-to-end.

Motivation

Addresses #2: the retrieval scorers were only covered by unit tests. This provides a small labelled corpus and two deterministic retrievers so the scorers, paired comparison and gate can run on a retrieval change.

Implementation

• examples/retrieval/cases.jsonl: 20 queries with graded relevance judgements.
• examples/retrieval/retrievers.py: good_retriever (term-overlap ranking) and noisy_retriever (simulates a regression by demoting the top hit on even-length queries).
• examples/retrieval/suite.yaml: configures the good retriever and gates on nDCG@5.
• examples/retrieval/README.md: usage instructions.

The example is fully deterministic and requires no models or network, matching the style of examples/deterministic.

Testing

The files were added via the GitHub API. The suite follows the same structure as existing examples and uses the public scorer types (recall_at_k, mrr, ndcg) already registered in the codebase. No local test run was possible in this environment; the change is additive and does not modify existing code.

Closes #2.

[technobasant]

Thanks for this. It does what #2 asked, and it makes a good teaching example: moving the top hit to rank 5 leaves recall@5 untouched while MRR and nDCG@5 drop, which is exactly why the three scorers exist.

I pushed one commit on top before merging:

• removed the unused import random and wrapped the long docstring, so ruff check passes (CI's lint job would have failed on both);
• the README now describes the regression as deterministic (the top hit drops to rank 5 on even-length queries), switches retrievers with --system instead of editing the suite, and records what the run shows: 9 of 20 queries regress, none improve, exact McNemar p = 0.0039, gate exit 1.

All eight CI jobs pass. Merging.