feat: add embeddings (self-supervised contrastive) modality

[shujaatTracebloc]

What

Enables the NLP embeddings / contrastive use case ("shape #5") on the data-ingestors side, mirroring the seq2seq wiring (closest sibling). The training container (tracebloc-engine #302) is already done; this is the ingestor half of the cross-repo wiring. Prerequisite for staging an embeddings dataset.

On-disk contract: one .txt per sample under texts/, each a tab-separated anchor<TAB>positive pair OR anchor<TAB>positive<TAB>negative triplet. No label column (self-supervised contrastive).

Touchpoints (mirrors seq2seq)

1. utils/constants.py — TaskCategory.EMBEDDINGS.
2. modalities/registry.py — ModalitySpec (file-bearing, self-supervised, NLP, texts/). is_nlp=True is the ingestor-side #805 tokenizer gating: it ships the data-derived text profile on the global-metadata channel for the contributor-tokenizer-fit check.
3. modalities/validators.py + new validators/contrastive_pairs_validator.py — validates the on-disk format. Beyond the shared TextContentValidator (UTF-8/binary hygiene), the new centralized ContrastivePairsValidator rejects any .txt that isn't exactly 2 or 3 non-empty tab fields (plain prose, empty field, 4+ fields, multi-line → rejected).
4. schema/ingest.v1.json — enum value, texts requirement, self-supervised no-label guard (Setting label: for a self-supervised category produces misleading backend HTTP 400 'No data found' #213).
5. modalities/transfer.py + cli/conventions.py — raw-text staging from texts/.
6. templates/embeddings/ — script + README + sample pairs/triplets; examples/yaml/embeddings.yaml; Readme entry.

Repo gotchas (verified not reintroduced)

• Fail loudly: the template routes through the shared run_ingestion helper (no exit 0 on hard failure) — pinned by test_modality_failure_accounting / test_batch_send_failure_accounting.
• No zip(ids, batch) mispair: the send path is untouched; embeddings reuses the existing text_transfer + base ingestor.
• Centralized validation (refactor(validators): compose common validators centrally (supersedes #316) #317): the structural check lives in validators/, not a per-template copy.

Tests

• New tests/test_embeddings.py (wiring, mirrors test_seq2seq.py) and tests/test_contrastive_pairs_validator.py (structural unit tests).
• Updated enumerating tests (registry NLP set, validators_mapping, template_equivalence, schema_validation, modality_failure_accounting _TEMPLATE_CATEGORIES) and e2e params.
• Full suite green: 1312 passed, 1 xfailed; total coverage 97% (≥95 gate), new validator at 100%.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches the published ingest schema and modality registry (new category must stay in sync everywhere), but behavior reuses existing text transfer and adds validation-only constraints rather than changing core ingest paths.

Overview
Adds a new embeddings NLP ingest category for self-supervised contrastive training: CSV manifest plus one .txt per sample under texts/, each file holding either anchor<TAB>positive or anchor<TAB>positive<TAB>negative (no label: — same self-supervised guard as seq2seq/MLM, #213).

Wiring mirrors seq2seq (file-bearing, NLP, text_transfer from texts/) but adds ContrastivePairsValidator so ingest rejects malformed shapes (wrong field count, empty fields, multi-line files) that free-form seq2seq/causal LM would allow. TaskCategory.EMBEDDINGS, modality registry, ingest.v1.json, and CLI TEXT_CATEGORIES are updated; templates/embeddings/, examples/yaml/embeddings.yaml, and README docs ship sample data.

E2E/characterization suites and registry, schema, validator-mapping, template-equivalence, and modality tests are extended so the 14th category stays congruent end-to-end.

^{Reviewed by Cursor Bugbot for commit 347e52b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit eef0dff. Configure here.}