ClinCode is an AI-assisted medical coding platform designed to support the conversion of unstructured clinical documentation into evidence-backed ICD-10-CM code suggestions. The project addresses limitations in manual and keyword-driven computer-assisted coding, particularly errors caused by negation, family history, historical conditions, uncertainty, conflicting documentation, and unsupported free-form code generation. The proposed workflow combines clinical named entity recognition, assertion detection, hybrid retrieval, cross-encoder reranking, confidence calibration, retrieval-augmented generation (RAG), and a multi-agent investigation workflow coordinated with LangGraph. Candidate codes are retrieved from an ICD-10-CM knowledge base rather than freely invented by a language model, and suggested codes are linked to supporting evidence from the clinical note. Low-confidence or conflicting cases can be routed to an investigation team comprising an Evidence Analyst, Guideline Analyst, Specificity Agent, Query Drafter, Adversarial Verifier, and Supervisor. The platform is explicitly human-in-the-loop: the medical coder remains responsible for the final decision. The project specification also includes FastAPI APIs, a React review console, PostgreSQL storage, Redis background processing, and MLflow/DVC for model and dataset versioning. This manuscript presents the proposed system, workflow, technical components, and design-level improvements described in the project specification.
Clinical documentation contains symptoms, findings, diagnoses, test results, history, and other information that must be interpreted before documented diagnoses can be converted into standardized ICD-10-CM codes. The ClinCode project identifies the manual interpretation of this unstructured documentation as time-consuming and vulnerable to context-related errors.
The project specification highlights several challenging cases. A clinical note can mention multiple conditions even though not all should be coded. Negation can make a condition appear in the text even though the patient does not have it; for example, “No evidence of pneumonia” should not be interpreted as an active pneumonia diagnosis. Similarly, family history and historical conditions require contextual interpretation. The specification also notes that uncertain or conflicting charts require deeper investigation and that unrestricted LLM-based code generation can produce plausible but unsupported codes.
ClinCode therefore proposes a controlled, evidence-grounded workflow rather than direct free-form generation. The aim is to identify relevant clinical entities, determine their assertion context, retrieve appropriate ICD-10-CM candidates, rerank them, verify their support, and present evidence to a human medical coder.
The supplied ClinCode project specification characterizes traditional computer-assisted coding (CAC) as largely keyword-driven and identifies context understanding as a central limitation. It contrasts keyword matching with clinical NLP, assertion detection, hybrid retrieval, reranking, evidence-linked suggestions, guideline retrieval, and human review.
The project also positions retrieval-augmented generation as a grounding mechanism. Instead of asking an LLM to invent ICD-10-CM codes, the proposed system retrieves candidate codes and relevant coding guidelines from controlled collections. Retrieval-augmented generation was introduced as a way of combining parametric language models with retrieved non-parametric knowledge to improve factual, knowledge-intensive generation (Lewis et al., 2020). The specification further introduces a multi-agent investigation workflow for difficult cases. Recent research has also explored orchestrator-based multi-agent clinical decision-support architectures, although such systems require careful evaluation of reliability and failure modes (Orchestrator multi-agent clinical decision support system, 2026). The supplied project document does not contain a formal bibliography, so the references below were added from verified external literature.
ClinCode is designed as a human-in-the-loop pipeline for clinical documentation and ICD-10-CM coding. The methodology described in the project specification consists of sequential clinical language understanding, retrieval, ranking, verification, confidence-based routing, and human review.
The system reads an unstructured clinical note and uses clinical named entity recognition (NER) to identify medical entities such as conditions, procedures, medications, and anatomy. Bio_ClinicalBERT is specified for clinical NER, with SciSpaCy serving as a fallback clinical NLP component. Domain-specific ClinicalBERT models have been developed for clinical text and shown to improve performance on several clinical NLP tasks (Alsentzer et al., 2019).
After entity extraction, an assertion classifier determines whether a clinical condition is present, negated, possible, historical, associated with family history, or conditional. This step is intended to prevent the retrieval stage from treating every medical term in a note as an active patient condition. Negation detection has long been recognized as an important clinical NLP problem; the NegEx work demonstrated an algorithmic approach for identifying negated findings in discharge summaries (Chapman et al., 2001).
ClinCode retrieves possible ICD-10-CM candidates using hybrid search that combines semantic and keyword retrieval. A cross-encoder then reranks the candidates to improve matching between the clinical context and candidate codes. The proposed approach uses retrieval rather than unrestricted LLM code generation. Recent reviews of AI-based ICD coding identify transformer-based and hybrid approaches as important directions while emphasizing the need for explainability, reproducibility, and validation across clinical settings (Mousavi Baigi et al., 2025; Recent Advances in AI for Automated ICD Coding, 2026).
The proposed RAG component retrieves official coding guidelines and previous coded-chart precedents. The system presents the selected suggestion together with the supporting evidence sentence so that a coder can verify why the suggestion was produced.
ClinCode separates high-confidence cases from difficult cases. Low-confidence, conflicting, or rule-sensitive cases can be routed to a six-agent investigation workflow coordinated by a Supervisor. The specified sequence is Evidence Analyst, Guideline Analyst, Specificity Agent, Query Drafter when documentation is incomplete, and Adversarial Verifier, under Supervisor coordination.
The agents do not replace the medical coder. They investigate difficult cases and return an evidence-linked report. The human coder accepts, rejects, or modifies the final coding suggestion.
| Bio_ClinicalBERT | Clinical named entity recognition. |
| SciSpaCy | Fallback clinical NLP processing. |
| Assertion Classifier | Determines present, negated, possible, historical, family-history, and conditional context. |
| Qdrant | Stores and searches ICD-10 code and related retrieval collections. |
| Hybrid Search | Combines semantic and keyword retrieval for candidate codes. |
| Cross-Encoder | Reranks retrieved code candidates. |
| RAG | Retrieves coding guidelines and previous coded-chart precedents. |
| LangGraph | Coordinates the six-agent investigation workflow. |
| LLM | Generates grounded explanations and CDI queries without freely inventing codes. |
| FastAPI | Backend APIs. |
| React | Medical coder review console. |
| PostgreSQL | Stores documents, suggestions, reviews, audit data, and workflow state. |
| Redis | Queue and background job processing. |
| MLflow / DVC | Model, experiment, and dataset versioning. |
The supplied project specification describes the following design-level outcomes of the proposed ClinCode workflow. These are presented as system outcomes rather than quantitative experimental measurements because the source project document does not provide benchmark results, dataset sizes, or evaluation metrics.
| Mostly keyword-driven | Clinical NLP and context/claim understanding |
| Can confuse negated conditions | Assertion detection identifies negation |
| Can confuse family history with patient condition | Assertion classification distinguishes family history |
| Suggests codes from matching terms | Hybrid retrieval with cross-encoder reranking |
| Limited explanation/evidence | Suggestions are linked to source evidence |
| Difficult cases remain mainly manual | Low-confidence/conflicting cases receive agent investigation |
| Limited guideline reasoning | RAG retrieves official coding guidelines |
| Pure LLM generation can hallucinate codes | Codes are retrieval-based and the LLM is grounded |
| Same general workflow for cases | Confidence-based triage separates routine and difficult cases |
| Manual corrections may not form a structured learning loop | Coder actions are captured as feedback for future improvement |
The project specification also provides a worked example in which a note contains acute-on-chronic systolic heart failure, denial of chest pain, and a family history of diabetes. ClinCode is designed to classify heart failure as present, chest pain as negated, and diabetes as family history before code retrieval, reducing the risk that unsupported terms are treated as active conditions.
The central design choice in ClinCode is to avoid treating medical coding as unrestricted text generation. The proposed architecture separates clinical interpretation from code retrieval and uses evidence and guidelines to constrain downstream reasoning. This design is particularly relevant to cases in which surface-level keyword matching is insufficient.
Another important feature is risk-based routing. Rather than forcing every chart through the same level of automated reasoning, the system can send low-confidence, conflicting, or rule-sensitive cases to a deeper investigation workflow. The human-in-the-loop design further limits the role of automation by keeping the final coding decision with the medical coder.
The current project specification does not provide empirical validation. Quantitative evaluation would therefore be required to establish the effectiveness of the proposed system. Future evaluation should measure entity recognition and assertion classification, retrieval and reranking quality, end-to-end coding performance, evidence support, and the behavior of the confidence-based investigation workflow.
ClinCode is an AI-assisted medical coding framework that combines clinical NLP, assertion detection, hybrid retrieval, cross-encoder reranking, RAG, confidence-based triage, multi-agent investigation, and human review. Its primary design objective is to produce evidence-backed ICD-10-CM suggestions without relying on unrestricted LLM code generation. The proposed workflow is designed to distinguish active conditions from negated, historical, possible, and family-history mentions and to provide deeper investigation for difficult cases.
The project specification demonstrates a coherent architecture and a clear distinction from a simple keyword-based CAC workflow. Recent systematic reviews similarly identify AI-based ICD coding as a promising research direction while highlighting the importance of validation, rare-label performance, reproducibility, and explainability (Mousavi Baigi et al., 2025; Recent Advances in AI for Automated ICD Coding, 2026). A complete research evaluation is still required before final submission, including a defined dataset, experimental protocol, quantitative results, and a verified bibliography.
I/We agree that this article is published under the journal’s open-access licence (CC BY 4.0) and that the authors retain copyright.
None
Replace with the actual contributions of each author using CRediT roles. The supplied project document does not provide author contribution information.
This research received no external funding.
The author declares no conflict of interest.
No new clinical dataset was generated or analyzed in this study. The work presents an AI-assisted framework and system design for medical coding.
The supplied project specification does not state that human participants were enrolled or that clinical records were collected for research. The authors should provide the applicable ethics approval and consent information, or state “Not applicable” only if that is factually correct for the study.
This manuscript draft was prepared with assistance from a generative AI system for organization and language drafting based on the supplied ClinCode project specification. The authors remain responsible for verifying all technical claims, data, references, and final manuscript content.