sankar-raul/ICD-10-code-predictor-env

1---2title: Medical Coding Assistant Environment Server3emoji: 🏥4colorFrom: blue5colorTo: gray6sdk: docker7pinned: false8app_port: 80009base_path: /web10tags:11  - openenv12---13 14# Medical Coding Assistant15 16Medical Coding Assistant is an OpenEnv environment for evaluating agents on a real clinical-operations workflow: assigning ICD-10 diagnosis codes from short chart summaries. The environment is intentionally scoped to a closed, offline code set so that grading is deterministic, reproducible, and safe for a hackathon setting.17 18This environment targets coding workflow automation, not diagnosis or treatment. The agent receives curated chart excerpts and must choose supported diagnosis codes, optionally add supporting secondary codes, and escalate ambiguous encounters for human review when required.19 20## Motivation21 22Medical coding is a real-world task performed by revenue-cycle and documentation teams. It has the right properties for an RL environment:23 24- real human workflow rather than a toy game25- typed actions and observations26- deterministic grading against gold codes27- dense feedback through intermediate draft quality28- clear penalties for unsupported or destructive actions29 30## Environment Overview31 32Each episode loads one fixed task and exposes a small allowed code set. The agent can iteratively refine a coding draft over multiple steps before finalizing.33 34### Action Space35 36`MedicalCodingAction`37 38- `primary_code`: proposed primary ICD-10 code39- `secondary_codes`: proposed supporting ICD-10 codes40- `needs_review`: whether a human coder should review the chart41- `request_hint`: reveal the next deterministic hint42- `finalize`: end the task and score the current draft43 44### Observation Space45 46`MedicalCodingObservation`47 48- `task_id`: current task key49- `difficulty`: `easy`, `medium`, or `hard`50- `objective`: task objective51- `encounter_text`: offline chart excerpt52- `allowed_codes`: closed label set for the task53- `revealed_hints`: hints shown so far54- `current_primary_code`: current draft primary code55- `current_secondary_codes`: current draft secondary codes56- `current_needs_review`: current review draft flag57- `attempts_remaining`: remaining step budget58- `progress_score`: best deterministic grader score reached so far59- `grader_feedback`: reproducible textual feedback from the grader60- `reward_breakdown`: typed `RewardBreakdown` model with score delta and penalties61 62### State63 64`MedicalCodingState`65 66- episode metadata and step count67- current task and difficulty68- current draft codes and review flag69- best score reached so far70- hints used and repeated-action count71- completion flag72 73## Tasks74 75The environment ships with three tasks that increase in difficulty.76 77### Easy: `easy_t2dm_followup`78 79- Objective: code uncomplicated type 2 diabetes and capture long-term oral hypoglycemic use.80- Gold answer: primary `E11.9`, secondary `Z79.84`81- Difficulty driver: basic specificity and status-code capture.82 83### Medium: `medium_hypertensive_ckd`84 85- Objective: use the hypertensive CKD combination diagnosis and add the documented CKD stage.86- Gold answer: primary `I12.9`, secondary `N18.30`87- Difficulty driver: choosing the combination code instead of coding isolated hypertension.88 89### Hard: `hard_chest_pain_review`90 91- Objective: code documented symptoms while escalating an unresolved acute coronary syndrome workup for review.92- Gold answer: primary `R07.9`, secondary `R94.31`, `needs_review=True`93- Difficulty driver: avoiding unsupported definitive diagnoses and recognizing when human review is necessary.94 95## Grading96 97Each task has a deterministic grader in [grading.py](/D:/projects/hackathon/Learn/Build%20My%20RL%20Agent/medical_coding_assistant/grading.py).98 99Scoring rules:100 101- exact primary code: `+0.60`102- accepted but less specific primary alternate: `+0.50`103- right code family, wrong specific code: `+0.30`104- correct secondary support codes: up to `+0.25`105- correct review flag: `+0.15`106- unsupported extra secondary codes: penalty up to `-0.15`107 108The grader always returns a score in `[0.0, 1.0]`.109 110## Reward Function111 112The environment gives feedback throughout the trajectory instead of only at completion.113 114- reward equals improvement over the best grader score achieved so far115- `request_hint=True` applies a small penalty116- invalid codes outside the allowed set apply a penalty117- repeating the same draft applies a penalty118- timing out by exhausting the step budget applies a penalty119 120This encourages incremental progress toward the objective while discouraging infinite loops and unsupported edits.121 122## OpenEnv Interface Compliance123 124This environment is compliant with the OpenEnv server interface used by `openenv validate`.125 126- Typed models:127  - action: `MedicalCodingAction`128  - observation: `MedicalCodingObservation`129  - reward details: `RewardBreakdown` (embedded in observation)130  - state: `MedicalCodingState`131- API shape:132  - `reset(...) -> observation`133  - `step(action, ...) -> observation`134  - `state` property exposes current typed state135- Gym-style tuple mapping:136  - OpenEnv transports `observation`, `reward`, and `done` in the step response payload.137  - `info` is provided in `observation.metadata["info"]`.138 139Validation status in this workspace:140 141```bash142openenv validate .143# [OK] : Ready for multi-mode deployment144```145 146## Setup147 148```bash149cd medical_coding_assistant150uv sync151```152 153## Run Locally154 155```bash156uv run --project . server157```158 159Or:160 161```bash162uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload163```164 165## Validate166 167```bash168openenv validate .169```170 171If `openenv` is not on your shell PATH (common on Windows), run the venv executable directly:172 173```powershell174& "..\.venv\Scripts\openenv.exe" validate .175```176 177## Docker178 179Build:180 181```bash182docker build -t medical-coding-assistant:latest -f server/Dockerfile .183```184 185Run:186 187```bash188docker run --rm -p 8000:8000 medical-coding-assistant:latest189```190 191## Hugging Face Spaces192 193This repository is now ready to publish as a Hugging Face Docker Space.194 195Use the repo root `Dockerfile` and keep the existing README metadata block with `sdk: docker` and `app_port: 8000`. After pushing to Hugging Face, the Space will start the FastAPI app from `server.app:app` on port `8000`.196 197Live Space: [sankar-raul/ICD-10-code-predictor-env](https://huggingface.co/spaces/sankar-raul/ICD-10-code-predictor-env)198 199## Usage Example200 201```python202from medical_coding_assistant import MedicalCodingAction, MedicalCodingAssistantEnv203 204client = MedicalCodingAssistantEnv(base_url="http://localhost:8000").sync()205 206with client:207    reset_result = client.reset(task_id="easy_t2dm_followup")208    print(reset_result.observation.encounter_text)209 210    result = client.step(211        MedicalCodingAction(212            primary_code="E11.9",213            secondary_codes=["Z79.84"],214            finalize=True,215        )216    )217    print(result.reward, result.done, result.observation.progress_score)218```219 220## Baselines221 222Reference heuristic baseline executed locally:223 224- easy: `1.00`225- medium: `1.00`226- hard: `1.00`227- macro average: `1.00`228 229LLM baseline reproduction script:230 231- file: [baseline_inference.py](/D:/projects/hackathon/Learn/Build%20My%20RL%20Agent/medical_coding_assistant/baseline_inference.py)232- client: OpenAI Python SDK233- auth: `HF_TOKEN`234- transport: Hugging Face Inference Router OpenAI-compatible API235 236`HF_TOKEN` was not available in this workspace, so the OpenAI-compatible baseline was added but not executed here.237 238Run the offline reference baseline:239 240```bash241python baseline_inference.py --mode heuristic242```243 244## Dataset Learning Simulation245 246You can simulate incremental learning directly from [diagnoses.csv](/D:/projects/hackathon/Learn/Build%20My%20RL%20Agent/medical_coding_assistant/data/diagnoses.csv):247 248```bash249python -m medical_coding_assistant.simulate_learning --csv medical_coding_assistant/data/diagnoses.csv --warmup 1000250```251 252Sample result in this workspace:253 254- rows_total: `274592`255- rows_warmup: `1000`256- rows_evaluated: `273592`257- accuracy: `0.2352`258 259## Project Structure260 261```text262medical_coding_assistant/263├── __init__.py264├── baseline_inference.py265├── client.py266├── grading.py267├── models.py268├── openenv.yaml269├── outputs/270├── pyproject.toml271├── README.md272├── tasks.py273└── server/274    ├── __init__.py275    ├── app.py276    ├── medical_coding_environment.py277    ├── Dockerfile278    └── requirements.txt279```280