Files

T

Brummel d83b10f939 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>

2026-05-31 19:15:08 +02:00

4.3 KiB

Raw Blame History

Glossary

Canonical nomenclature for alpha-id. This file is the source of truth for the project's terminology: where any other document names a concept differently, the canonical entry here — and its Avoid list — wins. Each block is a canonical term, an Avoid line of synonyms not to use, and a definition of at most two sentences. (Canonical terms are English, per the repo-English rule; the spec's German prose forms appear as synonyms to avoid.)

alpha-id

Avoid: — The Rust tool and CLI binary that turns caller-extracted diagnostic phrases into a ranked list of ICD-10-GM code suggestions. Distinct from Alpha-ID, the upstream data source it consumes.

Alpha-ID

Avoid: — The BfArM Alpha-ID dataset mapping free-text diagnosis phrases to ICD-10-GM codes; the source of the match corpus. Distinct from alpha-id, the tool that consumes it.

extracted phrase

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 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 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 An ICD code marked Para295 == "P" in ClaML, i.e. valid as a standalone billing diagnosis. The --billable-only filter and the BillableRecall@10 metric key off this tag.

ClaML

Avoid: — The Classification Markup Language XML distribution of ICD-10-GM, parsed for code metadata (chapter, billability, descriptions) and for modifier expansion.

modifier expansion

Avoid: subclassification, Subklassifikation The ClaML process of generating terminal sub-digit codes (e.g. E11.90) by applying <ModifierClass> definitions, referenced via <ModifiedBy>, to a parent category. Produces the synthesized billable leaf codes the corpus matches against.

RRF

Avoid: — 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 Hybrid cross-encoder step that rescores the fused candidate pool against the query phrase, using the IONOS reranker model.

corpus

Avoid: Korpus, match corpus The set of Alpha-ID phrase entries that retrieval matches against.

embedding store

Avoid: embedding cache The per-phrase, content-hash-keyed persistent store of corpus embeddings under index/. Resumable, so an interrupted full embedding run can be continued.

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 Hybrid degrades.

degrade

Avoid: — 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: — The predicate that drops suggestions by their tags — billable_only, valid_only, exclude_exotic, and chapters — applied after ranking and before truncating to the top-k.

eval harness

Avoid: — The offline evaluation that injects transcription errors into known billable phrases and measures whether the true code returns in the top-10.

exotic

Avoid: — An ICD code tagged Meta == "J" in ClaML, marking a rare/exotic code; removable via --exclude-exotic.

chapter

Avoid: — The ICD-10-GM chapter, stored as a zero-padded two-digit string ("01".."22") derived from the ClaML Roman-numeral chapter code. The --chapters filter matches against this value.

BillableRecall@10

Avoid: — The project's lead metric: the share of billable-code eval cases whose true code appears in the top-10 suggestions.

4.3 KiB Raw Blame History