mihikajadhav/medical-coding-auditor

Medical Coding Auditor — OpenEnv RL Environment

Overview

An RL environment that trains AI agents to audit US medical billing claims. The agent reads freeform clinical notes and determines whether CPT procedure codes and ICD-10 diagnosis codes accurately reflect the documented services.

This environment targets the $60B/year problem of fraudulent upcoding in Medicare/Medicaid billing — a task that genuinely requires natural language understanding and cannot be solved with a rule engine.

Why This Needs RL

Clinical notes are unstructured natural language. Mapping from a freeform doctor's note to correct billing codes requires understanding medical terminology, visit complexity, and what is vs is not documented. A rule engine cannot do this — the agent must learn to reason like an experienced medical auditor across thousands of varied cases.

Task Description

The agent receives a clinical note and billing codes, then must:

1. 1.Optionally ask clarifying questions (up to 2 per episode)
2. 2.Submit a verdict: correctly_coded / upcoded / undercoded / fraudulent
3. 3.Identify the specific wrong codes
4. 4.Justify its reasoning

Action Space

Observation Space

Reward Function

Tasks

Baseline Scores

Run uv run inference.py to reproduce baseline scores.

Scores below were produced with gpt-4o via the OpenAI API. The same model was used for both the auditing agent and the LLM justification judge.

The hard split remains the useful training signal: cases involving bundling, observation vs inpatient status, and procedure-code nuance still produce meaningful errors even when simpler documentation gaps are solved.

Setup

docker build -t medical-coding-auditor .
docker run -p 8000:8000 medical-coding-auditor
cp .env.example .env   # set API_BASE_URL, MODEL_NAME, and HF_TOKEN
uv run inference.py

For OpenAI-compatible endpoints, set HF_TOKEN to the API key for that endpoint:

API_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o
HF_TOKEN=your_api_key_here

For Hugging Face router models, use:

API_BASE_URL=https://router.huggingface.co/v1
MODEL_NAME=Qwen/Qwen2.5-72B-Instruct
HF_TOKEN=your_hugging_face_token_here

inference.py is in the repository root and emits only the required structured stdout lines:

[START] task=<task_name> env=medical-coding-auditor model=<model_name>
[STEP] step=<n> action=<json_action> reward=<0.00> done=<true|false> error=<msg|null>
[END] success=<true|false> steps=<n> score=<score> rewards=<r1,r2,...>

Deploy

openenv push --repo-id your-hf-username/medical-coding-auditor --exclude .openenv-push-exclude