Brummel
1ce863f76c
Add .claude/dev-cycle-profile.yml (skills-plugin profile) with paths.glossary pointing at the new docs/glossary.md, so the glossary becomes standing reading for every role. The glossary pins 19 canonical terms bootstrapped from the design spec and source doc comments; canonical forms are English (repo-English rule), German spec-prose forms listed under Avoid. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
# 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 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 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.
|
|
|
|
### 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 A.
|
|
|
|
### rerank
|
|
**Avoid:** —
|
|
The Mode A 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 A 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`.
|
|
|
|
### 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.
|