Add index.subsample() to resize an index without re-encoding

[wxiao0421]

Stacked on #32. Base branch is feat/persist-corpus-and-deterministic-load, so this diff shows only subsample() and its tests. Merge #32 first.

Encoding a sentence produces the same numbers regardless of which index it ends up in, so a 1,000-example index is just a 10,000-example one with 9,000 rows deleted. There is currently no way to exploit that: resizing means re-encoding the whole corpus from scratch, which makes sweeping index size — the highest-leverage knob there is — too expensive to bother with outside the internal pipeline.

subsample() copies the rows you want instead:

smaller = index.subsample(n_positive=1000, neg_to_pos_ratio=5.0, seed=42)

On the shipped examples/hate_speech_model index, building a 3×3 grid takes 9 ms against roughly 12.5 s to re-encode the same 16,100 rows. Around 1,400× faster, and the gap widens with the grid.

Design decisions worth reviewing

• Returns a new instance and never mutates the receiver. Callers loop over sizes, so if each call shrank the original, run 2 would start from run 1's leftovers and every later result would be silently wrong. This deliberately differs from _apply_negative_ratio, which mutates in place — fine there, because it runs once inside load().
• Positives are chosen first, since the ratio is defined relative to how many positives survive. neg_to_pos_ratio=None leaves negatives untouched.
• Invalid sizes raise, the one departure from the existing warn-and-continue style. A grid search that quietly ignored a bad argument would emit rows describing an index nobody asked for.
• scale_fn, encoding kwargs and model card carry over, and the sentence model is shared rather than reloaded. A dropped scale_fn would silently change scores for models like E5.
• Reuses _take_rows() and the private-torch.Generator seeding convention from Persist the corpus and make index loading deterministic #32, so corpus alignment is handled in one place.

This is a new method: no existing signature or behaviour changes, and nothing calls it yet. The caller arrives in #34.

Test plan

15 new tests, 82 total (was 67). The load-bearing ones assert that the original index is unchanged after repeated calls, that repeated calls are independent of each other, and that corpus texts still track their own embedding rows on both sides. Also covers seeding, clipping when over-asking, carry-over of scale_fn/kwargs/model card, corpus-less indices, and ValueError on invalid sizes. flake8 output is unchanged from base and docs/check_docs_sync.py reports in sync.

No CI checks appear because .github/workflows/test.yml only triggers on pull requests targeting main. Run locally on Python 3.10; the full 3.10/3.11/3.12 matrix runs once the stack retargets.

[vcai4071]

LGTM!

[vcai4071]

edge case: if we are doing a grid search with positive to negative ratio, if there is one run in the search where we want to keep all the positive rows, then torch.randperm(available, generator=generator) will not run, which means the stateful generator will be at a different state, and thus the negative embedding set will be different.