title	Medical Coding Environment
emoji	🏥
colorFrom	blue
colorTo	green
sdk	docker
pinned	false

🏥 Medical Coding Environment (OpenEnv)

This project implements a custom OpenEnv-compatible environment for evaluating automated medical coding systems. The environment simulates clinical scenarios and requires an agent to assign correct ICD-10 and CPT codes.

---

🚨 Problem Statement

With the rise of ICT (Information and Communication Technology) in healthcare systems, fraud and inaccuracies in medical billing have become a serious issue.

Common problems include:

• Incorrect or manipulated medical codes
• Fraudulent insurance claims
• Overbilling or underbilling (upcoding/downcoding)
• Data inconsistencies in digital health records

These issues lead to financial losses, reduced trust, and inefficiencies in healthcare systems.

This project simulates a simplified version of this problem by requiring an AI agent to correctly assign medical codes from clinical notes. It demonstrates how intelligent systems can help reduce errors and detect inconsistencies in medical coding workflows.

---

🧠 Environment Description

The environment presents clinical notes describing patient conditions. The agent must interpret these notes and return structured medical codes.

Each episode consists of 3 tasks:

• Easy: Simple diagnosis (e.g., streptococcal pharyngitis)
• Medium: Multi-condition case (e.g., hypertension + diabetes)
• Hard: Complex case (e.g., fracture with medical history)

The order of tasks is randomized, and clinical notes include slight variations to simulate real-world inconsistencies.

---

📥 Observation Space

Each step returns an observation with the following fields:

• patient_age (int): Age of the patient
• patient_sex (str): Gender of the patient
• clinical_note (str): Doctor's notes describing the case
• feedback (str): Feedback from the grader
• remaining_tasks (int): Number of tasks left

---

📤 Action Space

The agent must return an action with:

• primary_icd10 (str): Primary diagnosis code
• secondary_icd10s (List[str]): Secondary diagnosis codes
• cpt_codes (List[str]): Procedure codes

---

🎯 Reward Function

The reward is calculated based on:

• Partial match for correct ICD-10 and CPT codes
• Higher reward for exact matches
• Penalties for excessive or incorrect predictions

Final reward is normalized between 0.0 and 1.0 per step.

---

⚙️ Setup Instructions

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/medical-coding-env.git
cd medical-coding-env

2. Install dependencies

pip install -r requirements.txt

3. Setup environment variables

Create a .env file in the root directory: API_BASE_URL=https://router.huggingface.co/v1 MODEL_NAME=Qwen/Qwen2.5-72B-Instruct HF_TOKEN=your_huggingface_token

4. Run Inference

python inference.py

🐳 Docker Build the Docker image

docker build -t medical-env .

Run the container

docker run -p 8000:8000 medical-env

🌐 API Endpoints POST /reset → Initialize environment POST /step → Execute an action GET /state → Retrieve current state

🧪 Inference Script The inference.py script: Uses OpenAI-compatible client with Hugging Face router Interacts with the environment step-by-step Outputs structured logs in required format: [START] [STEP] [END]

📈 Example Output [START] task=medical-coding env=medical-coding-env model=Qwen/Qwen2.5-72B-Instruct [STEP] step=1 action=... reward=1.00 done=false [STEP] step=2 action=... reward=0.99 done=false [STEP] step=3 action=... reward=0.81 done=true [END] success=true steps=3 score=0.94 rewards=1.00,0.99,0.81

⚠️ Notes .env is used for local development only Hugging Face Spaces requires environment variables via Secrets Do not modify log format in inference.py