Add SentinelLocalIndex.from_texts() to build an index in one line

[wxiao0421]

Stacked on #32 (→ #31). Base branch is feat/persist-corpus-and-deterministic-load.

This one branches off the stack rather than sitting on top of it. Its only real dependency is the _take_rows helper from #32, so basing it there lets it merge as soon as #32 lands, without waiting on #33 and #34.

Summary

Building an index today is eight manual steps (the README's "Creating a New Index" recipe), and two of them fail silently when skipped:

• Forget normalize_embeddings=True → the similarity maths quietly returns wrong numbers.
• Forget to pass the corpus → explanations degrade to row numbers.

Neither raises. Neither warns. You just get subtly wrong or unexplainable results, and nothing tells you why. That is the real cost here, not keystrokes: doing these steps inside the library, where they are tested, means a caller cannot forget a step they never have to write.

index = SentinelLocalIndex.from_texts(
    positive_texts=[...],
    negative_texts=[...],
    neg_to_pos_ratio=5.0,
    seed=42,
)

Verified end to end — the resulting index scores correctly, its embeddings are unit-length, and its explanations name real sentences that survive a save/load round trip:

built in one call: 3 pos / 3 neg
normalized: True
corpus kept: True

explanation names real sentences, not row numbers:
   [+] 'they are invading our nation'
   [+] 'our people are being replaced'

after save+load, corpus survives: True

Implementation details worth reviewing

• Keeps both return values of get_sentence_transformer_and_scaling_fn. Dropping scale_fn is a silent scoring bug for models like E5.
• Hoists the encoding defaults into DEFAULT_ENCODING_KWARGS, now used by both the constructor and from_texts, rather than writing normalize_embeddings=True in a second place. Two copies of a default eventually disagree, and this one disagreeing would be invisible.
• Always passes the corpus through — half the point of the method.
• Applies neg_to_pos_ratio via the shared _take_rows helper from Persist the corpus and make index loading deterministic #32, with the same private-torch.Generator seeding convention used everywhere else in the library.
• Validates input before any encoding happens, including the bare-string case. A string is iterable, so positive_texts="some text" would otherwise be encoded one character at a time: confusing, slow, and entirely silent.

What breaks if this is wrong

• If normalize_embeddings stopped being applied, every index built this way would score incorrectly with no error anywhere. Asserted directly by checking the embedding norms are 1.0, rather than just checking the kwarg was passed.
• If scale_fn were dropped, scores change silently for scaled models.
• If the corpus were not carried through, explanations silently revert to the row-number behaviour that Persist the corpus and make index loading deterministic #32 exists to fix.

Nothing existing changes behaviour: this is a new classmethod, plus a refactor that moves an existing default into a named constant without altering its value.

Docs

README's Creating a New Index now leads with the one-liner. The manual recipe is kept directly below under "Advanced: building an index manually" for anyone who needs custom encoding, a different backend, or precomputed vectors — with its two silent traps called out explicitly so the advanced path is safer too.

Test plan

12 new tests.

• One call produces a usable index that scores text
• The corpus is kept automatically
• Embeddings are unit-length by default (catches a silent normalization regression)
• neg_to_pos_ratio downsamples and the surviving negatives keep their own text
• Same seed → identical index
• The result saves and reloads with explanations intact
• Bare string instead of a list raises, for both arguments
• Empty list raises, for both arguments
• Non-positive ratio raises
• pytest tests/ — 79 passed (67 on the base branch)
• flake8 --config=.flake8 output byte-identical to base: zero new findings
• docs/check_docs_sync.py reports in sync

The validation tests run without loading a model, since they raise before any encoding; the rest are marked integration in line with the existing suite.

Note on CI: .github/workflows/test.yml only triggers on pull requests targeting main, so stacked PRs show no checks. Run locally against Python 3.10.

[vcai4071]

Looks good overall. Some comments that may be worth addressing.

[vcai4071]

This seems to be repeated code with subsample? Can we reuse some code here?

[wxiao0421]

Thanks for the suggestion. Fixed .

[vcai4071]

would it be worth downsampling before embedding to save some cost?

[wxiao0421]

Thanks for the suggestion. Fixed it improve performance.