We are happy to announce the release of the ICD Helper module: an AI-assisted ICD-10-CM coding tool developed as part of our Master’s thesis at University of Louvain, Belgium.
The module adds an offline coding assistant directly into the OpenMRS clinical workflow. Clinicians can select a visit note from the patient dashboard, analyze it with embedded AI models, and save suggested ICD-10-CM diagnosis codes to the patient’s record, all without any external API or cloud dependency at inference time.
A big thanks to the OpenMRS community for the resources and documentation that made this possible!
If you work in a clinical environment and are interested in trying the module, we would also love to hear about your experience. We have prepared a short usability survey; it only takes a few minutes and would be incredibly valuable for our master thesis:
This is amazing work, Emilie and Nora! An offline, AI-assisted ICD-10-CM coding tool integrated directly into OpenMRS is a game-changer, especially for low-resource clinical settings. Congrats on the release and best of luck with your Master’s thesis!
Thank you! The offline constraint was actually a core design choice, as OpenMRS deployments can run in low-connectivity environments, so depending on an external API would have made the tool more impractical. Happy to answer any questions if you’d like to know more about how it works under the hood
Thank you so much, that means a lot to us! Low-resource settings were indeed central in our design decisions throughout the project. We hope it can be useful to the community, and we’re very open to feedback from anyone who tries it in a real deployment context
We have signed up for a 5 minute presentation slot at the OpenMRS Community Virtual Showcase, scheduled for April 29–30. Is that the call you’re referring to?
This looks really interesting, especially the offline first design.
I’m curious, how are you handling updates to the ICD 10 data or model over time in an offline setup? Do deployments need manual updates, or is there some sync mechanism planned?
For the full note model, updates related to ICD-10-CM coverage are unlikely to be frequent because it’s trained on MIMIC-IV discharge reports, with the associated ICD codes. Updates to the training data/new releases are less regular than updates to the codes themselves.
The SapBERT selection mode is more flexible by design. The ICD-10-CM concept embeddings it searches against are precomputed and stored as a flat binary file, making the index straightforward to refresh as new codes are introduced.
In practice changes to both models, whether about code coverage or overall structure, follow the same steps: replace the files in the server model directory and restart the module. Our download script helps making that straightforward.
There’s no built-in sync mechanism yet, but given the modular structure it’s a realistic addition. A future release could check for updated model assets on startup and prompt the administrator, similar to how OpenConceptLab handles concept dictionary updates.
We’re curious whether automated update checking would be valuable for your use case; that kind of feedback helps us prioritize.
That makes a lot of sense, thanks for the detailed explanation, this is really helpful
The separation between the full note model and the SapBERT selection mode is really interesting, especially how the embeddings can be refreshed independently.
Automated update checking would definitely be useful in real deployments, especially to avoid manual steps and ensure consistency across environments. Even something like a notification on startup would be helpful.
Really cool design overall, thanks for sharing the insights!
Very impressive. I am actually surprised that it does so well as published literature has shown that mapping to ICD-10-CM is actually somewhat problematic. It would be interested to see how it validated compared to actual ICD-10-CM codes for those visits, and then of course, how it did on untrained visits.
One distinction, however, is that there is a difference between a visit diagnosis used for billing and those used for problem lists. The obs should be stored under visit diagnoses for ICD-10 coded diagnoses… particularly with ICD-10-CM which has billing-only modifiers like “subsequent visit”, etc.
ICD-10-CM is not used widely within the OpenMRS community, and it would also be good to know whether the model could be used for standard ICD-10-WHO codes. For OCL and CIEL-managed dictionaries, we recommend not mapping directly to ICD-10 but rather to an interface concept which has a curated map to both ICD-10 and SNOMED CT. This also handles complex clinical terminology and areas where direct ICD-10 mapping (not ICD-10-CM since CIEL does not map to ICD-10-CM) fails. OCL is currently evaluating a methodology using interface terminology bridge and direct algorithm mapping, but to ICD-11, not ICD-10.
Thank you for your feedback and the technical guidance.
We validated both models outside of OpenMRS: the Hierarchical BERT on a dedicated test split of MIMIC-IV that the model had never seen before, and SapBERT on a synthetic dataset. We unfortunately don’t have ground truth ICD codes associated with real OpenMRS visit notes to evaluate against. This is a known limitation, and part of why we designed a clinician survey to collect qualitative feedback on the tool’s suggestions in practice.
You are right about the Visit diagnoses saving of coded diagnoses. We take good note of that for a future release.
Regarding the choice of ICD-10-CM, it was driven by data availability. We used the MIMIC-IV dataset to train and evaluate the Hierarchical BERT, as it is one of the few accessible datasets providing clinical notes directly mapped to diagnostic codes. We decided to also align the SapBERT training target to ICD-10-CM for consistency of the tool, although we could switch this one to ICD-10-WHO without too many complications.
We completely understand the importance of mapping directly to interface concepts and then to standard ICD-10 (WHO) for the OpenMRS community. However, we haven’t yet found an open-access dataset comparable to MIMIC-IV, that links clinical notes to these specific concepts. It follows that modifying the model so it predicts against CIEL concept names and synonyms rather than ICD code descriptions seems feasible for SapBERT, but not for the model analyzing full notes.
We are very interested in refining our approach: if you know of any datasets or resources where notes are mapped to interface concepts, we would be eager to explore them.
Thank you again for your comments! It’s really helpful as we look to make this work more applicable to the broader OpenMRS ecosystem.
Thank you for the helpful response! Even if you could find a direct ICD-10-WHO mapped data set that would be helpful given the lack of ICD-10-CM in the OpenMRS community. I don’t know yet of a dataset with CIEL in the front end, but I am sure that IMOHealth (another interface terminology company mapped to ICD-10-CM) might have some customer data (or perhaps access to a research opportunity). I’ll ask. I know they do something similar commercially so they might not be enthusastic about an open source project :).
Thank you for looking into that, we really appreciate it. An ICD-10-WHO labeled dataset would indeed open up more relevant training possibilities for the OpenMRS context. Concerning IMOHealth, we understand the commercial sensitivity around open source, but it’s worth asking! We’ll keep an eye out for your follow-up, and please don’t hesitate to reach out to us directly if anything comes of it.
Thanks for the suggestion! Adding checkboxes is a great idea to make the selection visually clearer. We’ll implement them while keeping the entire row clickable, so users don’t have to aim for the specific box to toggle the selection.
