refactor: rename Mode variants C/A to Lexical/Hybrid (closes #2)

The retrieval-mode enum used opaque single letters `Mode { C, A }`;
neither the identifier nor the operator-facing `--mode a` token
conveyed what the mode does. Rename to self-describing names that map
directly onto the glossary definitions:

  Mode::C -> Mode::Lexical  (BM25 + tag filter, offline, no IONOS)
  Mode::A -> Mode::Hybrid   (lexical u semantic -> RRF -> rerank)

Decisions taken (the issue's open questions, resolved):
- CLI canonical tokens are now `lexical` / `hybrid`; the default is
  `lexical`. The legacy `c` / `a` tokens stay accepted as
  case-insensitive input aliases (zero cost; protects hand-typed
  invocations). A unit test pins the alias contract.
- The diagnostics `mode` string (Debug-derived) now emits
  "Lexical"/"Hybrid". Verified safe: no downstream consumer parses it.
  doctate is the future integrator and embeds the library (the `Mode`
  enum), not the JSON string (design spec §103).
- The reserved, out-of-scope generative tier (spec's "Mode B") keeps
  conceptual room: a future `Mode::Generative` does not collide with
  the retrieval-strategy names Lexical/Hybrid.

Surface: enum + FromStr, CLI defaults and `eval --mode both`
expansion, the private `collect_mode_c`/`collect_mode_a` methods (now
`collect_lexical`/`collect_hybrid`) and their comments, the two
pipeline mode test files (renamed), the eval CLI test, the glossary
(old letter forms demoted to Avoid lists), and the spec CLI synopsis.

closes #2

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-31 19:15:08 +02:00
parent 9a81f9eaf7
commit d83b10f939
10 changed files with 68 additions and 41 deletions
+10 -10
View File
@@ -20,13 +20,13 @@ The BfArM Alpha-ID dataset mapping free-text diagnosis phrases to ICD-10-GM code
**Avoid:** segment, unit, Einheit, Formulierung
One caller-extracted diagnostic phrase (one input line) — the unit that is matched and ranked. In source code this concept is carried by the identifier `segment` (e.g. `split_segments`, `source_segments`), which is retained as a code term only.
### Mode C
**Avoid:** Modus C
The lexical-baseline retrieval mode: BM25 over the corpus plus tag filtering, with no IONOS calls. Also the degrade target for Mode A.
### Mode Lexical
**Avoid:** Mode C, Modus C, mode c
The lexical-baseline retrieval mode: BM25 over the corpus plus tag filtering, with no IONOS calls. Also the degrade target for Mode Hybrid.
### Mode A
**Avoid:** Modus A, semantic mode
The hybrid retrieval mode: lexical and semantic (IONOS embedding) pools fused via RRF, then cross-encoder reranked. Degrades to Mode C on any IONOS failure.
### Mode Hybrid
**Avoid:** Mode A, Modus A, mode a, semantic mode
The hybrid retrieval mode: lexical and semantic (IONOS embedding) pools fused via RRF, then cross-encoder reranked. Degrades to Mode Lexical on any IONOS failure.
### billable
**Avoid:** abrechenbar, Abrechenbarkeit
@@ -42,11 +42,11 @@ The ClaML process of generating terminal sub-digit codes (e.g. `E11.90`) by appl
### RRF
**Avoid:** —
Reciprocal Rank Fusion: the rank-based method that merges the lexical and semantic candidate lists into one fused pool in Mode A.
Reciprocal Rank Fusion: the rank-based method that merges the lexical and semantic candidate lists into one fused pool in Mode Hybrid.
### rerank
**Avoid:** —
The Mode A cross-encoder step that rescores the fused candidate pool against the query phrase, using the IONOS reranker model.
The Mode Hybrid cross-encoder step that rescores the fused candidate pool against the query phrase, using the IONOS reranker model.
### corpus
**Avoid:** Korpus, match corpus
@@ -58,11 +58,11 @@ The per-phrase, content-hash-keyed persistent store of corpus embeddings under `
### vector index
**Avoid:** ANN index
The in-RAM matrix of corpus embeddings searched by exact cosine similarity for the semantic pool. Built only when every corpus entry has a cached embedding; otherwise Mode A degrades.
The in-RAM matrix of corpus embeddings searched by exact cosine similarity for the semantic pool. Built only when every corpus entry has a cached embedding; otherwise Mode Hybrid degrades.
### degrade
**Avoid:** —
Mode A falling back to Mode C when any IONOS step fails (embed, rerank, or a missing vector index); the request is still answered and `degraded` is set in diagnostics. Distinct from the 5-char-parent lookup fallback in `meta_lookup`.
Mode Hybrid falling back to Mode Lexical when any IONOS step fails (embed, rerank, or a missing vector index); the request is still answered and `degraded` is set in diagnostics. Distinct from the 5-char-parent lookup fallback in `meta_lookup`.
### tag filter
**Avoid:** —
@@ -197,9 +197,9 @@ alpha-id index build [--sample N | --full] [--confirm]
# Korpus+ClaML parsen, bge-m3-Embeddings,
# Lexik-+Vektorindex persistieren (resumierbar)
alpha-id suggest [FILE|-] # Formulierungs-Liste (eine pro Zeile) → Top-10
--mode c|a --top 10 --billable-only --valid-only
--mode lexical|hybrid --top 10 --billable-only --valid-only
--chapters I,J --exclude-exotic --json|--table
alpha-id eval --mode c|a --cases N --seed S [--gold PATH]
alpha-id eval --mode lexical|hybrid --cases N --seed S [--gold PATH]
```
- Config-TOML: IONOS-Endpoint/Modellnamen/Pool-Größen/Pfad-Defaults, per Flags überschreibbar.