kayodekosi/medical-icd10-coder-7b

kayodekosi/medical-icd10-coder-7b

Production-oriented ICD-10-CM medical coding assistant Built for hospital revenue-cycle management (RCM) and clinical documentation improvement teams.

Brief description: proposes ranked ICD-10-CM diagnosis codes from a clinical note or discharge summary, each with an evidence snippet and confidence score, returned as strict JSON for downstream RCM systems. A ready-to-deploy Gradio demo lives in `space/` — see the Deploying the demo Space section below.

Intended Hospital Use-Case

• —Suggest ICD-10-CM diagnosis codes from discharge summaries, progress notes, or operative reports.
• —Support MEAT criteria (Monitored, Evaluated, Assessed, Treated) evidence extraction.
• —Flag potential missed codes that are documented but not yet assigned.
• —Output a ranked code list with a short justification and confidence per code, as strict JSON.
• —Always requires certified coder / clinician final sign-off.

Model Details

Training Recipe

• —Supervised fine-tuning on (clinical text → ICD-10-CM codes) chat pairs.
• —Optional second stage: preference tuning on coder-preferred vs. incorrect codes.
• —Evaluation: exact-match / hierarchical accuracy on held-out public test sets + invalid-code rate.

See `train_config.yaml` and `train.py`.

pip install -r requirements-train.txt
python train.py --config train_config.yaml
python train.py --config train_config.yaml --push_to_hub --hub_repo_id kayodekosi/medical-icd10-coder-7b

Quickstart Inference

pip install -r requirements.txt
python inference.py --note sample_data/example_note.txt

This pulls the base model plus the fine-tuned LoRA adapter from the Hub by default. Point --adapter at a local checkpoint directory to test a fresh training run, or pass --adapter none for base-model-only output.

inference.py validates that the model's response is actually parseable JSON before treating it as structured output — malformed responses are surfaced as a warning rather than silently passed downstream, which matters for an RCM integration.

Example Output Format

{
  "codes": [
    {"code": "I21.9", "description": "Acute myocardial infarction, unspecified", "confidence": 0.92, "evidence": "elevated troponin, ST changes"},
    {"code": "E11.9", "description": "Type 2 diabetes mellitus without complications", "confidence": 0.85, "evidence": "history of T2DM, on metformin"}
  ],
  "missed_candidates": [],
  "notes": "Human coder review required. Not a substitute for certified coding."
}

Safety

• —The model can propose codes only; the final coding decision remains with a certified professional.
• —Recommended production hardening: filter invalid / non-billable codes post-generation against the official CMS code list, and reject any response that fails the JSON-schema check in inference.py.
• —Designed for air-gapped / VPC deployment.

Deploying the demo Space

`space/` is a complete, self-contained Gradio Space (app.py, requirements.txt, README.md with the Space metadata front matter). Deploy it with the portfolio-level script:

pip install -r ../../scripts/requirements.txt
huggingface-cli login
python ../../scripts/deploy_spaces.py --only icd10-coder

This creates kayodekosi/medical-icd10-coder-demo if it doesn't exist and uploads the whole space/ folder — nothing to copy by hand.

Repository Layout

02-icd10-medical-coder/
├── README.md                # this file / HF model card
├── train_config.yaml
├── train.py
├── inference.py               # loads base + adapter, validates JSON output
├── requirements.txt
├── requirements-train.txt
├── requirements-serving.txt
├── sample_data/example_note.txt
└── space/                     # Gradio demo Space (app.py + requirements.txt + README.md)

HF Path

kayodekosi/medical-icd10-coder-7b

Author: Kayode Okosi — kayodeokosi@gmail.com © 2026