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:
+10
-10
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user