Deploy: claude-code-for-health

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/architecture.png filter=lfs diff=lfs merge=lfs -text
+data/MedCalcBench/train_data.csv filter=lfs diff=lfs merge=lfs -text

CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+### Changed
+- **inference.py**: Set `TEMPERATURE = 0.0` for reproducible baseline (was 0.3)
+- **inference.py**: Added explicit `ValueError` if `HF_TOKEN` environment variable is missing
+- **inference.py**: Clarified score clamping to `(0.01, 0.99)` for normalization epsilon
+- **README.md**: Updated Tasks table with "Est. Frontier Score" column for each difficulty tier
+  - Clinical Note Review (Easy): 0.70–0.85
+  - Medical Calculation (Medium): 0.45–0.65
+  - Diagnostic Workup (Hard): 0.30–0.50
+- **README.md**: Corrected dataset sizes to reflect actual file counts
+  - MEDEC: 55,394 total (training 36,766 / validation 9,129 / test 9,499)
+  - MedCalc-Bench: ~138,000 total (numeric-answer rows only; train 136,969 / test 16,521)
+  - MedCaseReasoning: 766 structured clinical cases
+- **README.md**: Updated headline from "15,000+ real cases" to "194,000+ real cases"
+- **README.md**: Added note: "Each inference run picks one random case per difficulty level"
+- **README.md**: Added "Prior Work & Novelty" section with SDBench (Nori et al., 2025) citation
+- **README.md**: Expanded novelty claims with three key additions:
+  1. Multi-skill integration (note review + calculation + diagnosis)
+  2. Developer-native CLI interaction (same as Claude Code / aider / Codex)
+  3. Scale (194,000+ real cases, not curated vignettes)
+- **README.md**: Added Pydantic class definitions to Action/Observation space section
+- **README.md**: Added JSON action format examples to Action space
+- **README.md**: Added compliance note to Baseline Scores section on runtime and stdout format
+- **GitHub**: Created public repository at https://github.com/pratinavseth/claude-code-for-health
+
+### Fixed
+- **inference.py**: Reverted score clamping from `(0.0, 1.0)` back to `(0.01, 0.99)` (epsilon required for normalization)
+- **README.md**: Corrected all dataset row counts (external analysis had incorrect numbers)
+- **README.md**: Clarified that 194,000+ is the full data pool, not per-run consumption
+
+### Notes
+- All changes maintain backward compatibility with OpenEnv spec
+- Baseline inference completes in <5 minutes on standard hardware
+- Docker build and HuggingFace Space deployment remain compatible

Dockerfile

@@ -0,0 +1,81 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=claude_code_for_health
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,10 +1,287 @@
 ---
-title: Claude Code For Health
-emoji: 🌖
-colorFrom: pink
+title: Claude Code For Health Environment Server
+emoji: ⏲️
+colorFrom: yellow
 colorTo: yellow
 sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Claude Code for Health
+
+Medical AI is mostly tested on multiple-choice questions. This environment tests something harder: can an agent actually *do* clinical work, step by step, the way a real clinician does?
+
+Three task types, 194,000+ real cases, fully programmatic grading.
+
+## Motivation
+
+Medical errors are the third leading cause of death in the US, yet most AI benchmarks for medicine (MedQA, USMLE, PubMedQA) hand the model a complete question and ask for a single answer. That measures pattern recognition, not judgment.
+
+Real clinical work looks nothing like that. A clinician doesn't receive a pre-packaged summary — they read a history, order the right tests, interpret results in context, update their hypothesis, and commit to a plan. The reasoning happens over time, with incomplete information at every step.
+
+This environment forces that workflow. The agent interacts with a CLI — the same metaphor used by Claude Code, aider, and Codex for software engineering — but applied to patient care. It can only see what it explicitly requests, and it's graded on the full trajectory: what it looked up, how efficiently it got there, and whether its final answer was right.
+
+## Architecture
+
+![Architecture](assets/architecture.png)
+
+## Tasks
+
+| Task | Difficulty | Description | Dataset | Cases | Est. Frontier Score |
+|---|---|---|---|---|---|
+| **Clinical Note Review** | Easy | Read a clinical note, identify errors, correct them or approve | MEDEC | 55,394 | 0.70–0.85 |
+| **Medical Calculation** | Medium | Read a patient scenario, identify the formula, compute the answer | MedCalc-Bench | ~138,000 | 0.45–0.65 |
+| **Diagnostic Workup** | Hard | Explore a patient chart via CLI tools, build a differential, confirm diagnosis | MedCaseReasoning | 766 | 0.30–0.50 |
+
+## Datasets
+
+- **MEDEC** — 55,394 clinical notes with annotated errors and corrections across 3 splits (training: 36,766 / validation: 9,129 / test: 9,499)
+- **MedCalc-Bench** — ~138,000 medical calculation problems with ground truth answers and tolerance bounds (train: 136,969 / test: 16,521; numeric-answer rows only)
+- **MedCaseReasoning** — 766 structured clinical cases with demographics, vitals, labs, imaging, physical exam, and ground truth diagnoses (JSONL)
+
+Each inference run picks one random case per difficulty level — the full pools are available for training and evaluation at scale.
+
+## Prior Work & Novelty
+
+Most medical AI benchmarks test static knowledge: MedQA, USMLE, and PubMedQA all hand the model a complete question and ask for a single answer. That measures pattern recognition on full context, not the sequential decision-making that clinical work actually requires.
+
+The closest sequential benchmark is **SDBench** (Nori et al., 2025 — [arXiv:2506.22405](https://arxiv.org/abs/2506.22405)), which converts 304 NEJM case records into interactive diagnosis. Physicians scored only ~36% on hard cases, confirming that sequential reasoning under information constraints is a genuine challenge.
+
+This environment extends that line of work with three key additions:
+1. **Multi-skill integration** — note error correction, quantitative reasoning, and sequential diagnosis in one unified CLI interface, rather than diagnosis alone
+2. **Developer-native interaction** — pure CLI commands (exactly like Claude Code / aider / Codex), making this the first medical environment optimized for tool-use agents that already excel at software tasks
+3. **194,000+ real cases** from MEDEC, MedCalc-Bench, and MedCaseReasoning — not curated vignettes; dense per-step rewards mirror real clinical cost-efficiency trade-offs
+
+## Action / Observation Space
+
+**Action** — one CLI command string per step:
+```python
+class MedAction(Action):
+    command: str = Field(..., description="CLI command string, e.g. 'chart.labs CBC'")
+```
+
+The agent sends a single JSON object to the `/step` endpoint:
+```json
+{"command": "chart.labs CBC"}
+{"command": "ddx.confirm Adult-onset Still disease"}
+{"command": "submit 4.5"}
+{"command": "note.correct 3 Patient presented with altered mental status."}
+```
+
+Example command strings:
+```
+chart.history                       # view past medical history
+chart.labs CBC                      # view CBC panel results
+ddx.add Pulmonary Embolism          # add to differential
+ddx.confirm Pulmonary Embolism      # submit final diagnosis (ends episode)
+calculate Wells_PE                  # declare which calculator to use
+submit 4.5                          # submit numeric answer (ends episode)
+note.correct 3 Corrected text here  # fix error in sentence 3
+note.approve                        # approve note as-is (ends episode)
+```
+
+**Observation** — command output + episode context after each step:
+```python
+class MedObservation(Observation):
+    output: str                    # Command output text (chart data, lab results, etc.)
+    error: str                     # Error message if command was invalid (empty string if none)
+    available_commands: list[str]  # Tools valid for the current task type
+    task_type: str                 # "diagnosis" | "calculation" | "note_review"
+    step_number: int               # Current step count
+    max_steps: int                 # Hard cap (50 steps per episode)
+    done: bool                     # Inherited — episode complete?
+    reward: float                  # Inherited — step reward
+    metadata: dict                 # Inherited — additional info
+```
+
+**State** — episode tracking via GET /state:
+```python
+class MedState(State):
+    episode_id: str        # Inherited — unique episode identifier
+    step_count: int        # Inherited — total steps taken
+    task_type: str         # "diagnosis" | "calculation" | "note_review"
+    difficulty: str        # "easy" | "medium" | "hard"
+    total_score: float     # Cumulative reward accumulated so far
+    commands_issued: int   # Number of commands sent
+    is_submitted: bool     # Whether the agent has submitted a final answer
+```
+
+## Available Tools
+
+The environment simulates a real CLI tool interface - the same interaction pattern used by Claude Code, OpenCode, and Codex CLI for software engineering, but applied to clinical medicine. The agent issues text commands one at a time, receives structured output, and decides what to do next. No menus, no dropdowns - just a terminal and clinical judgment.
+
+### Diagnosis Tools
+```
+chart.history              View past medical history, medications, allergies
+chart.vitals               View vital signs
+chart.labs [panel]         View lab results (list panels or view specific)
+chart.imaging [type]       View imaging findings
+chart.exam [system]        View physical exam findings
+chart.medications          View current medications
+chart.allergies            View known allergies
+ddx.add <diagnosis>        Add to differential
+ddx.remove <diagnosis>     Remove from differential
+ddx.list                   Show current differential
+ddx.confirm <diagnosis>    Submit final diagnosis (ends episode)
+```
+
+### Calculation Tools
+```
+case.read                  Read the full patient note + question
+calculate <name>           Declare which calculator you're using
+submit <number>            Submit numeric answer (ends episode)
+```
+
+### Note Review Tools
+```
+note.read                  Read the clinical note with numbered sentences
+note.correct <id> <text>   Correct a sentence by ID
+note.approve               Approve note / submit corrections (ends episode)
+```
+
+### Reference Tools (all tasks)
+```
+reference.ranges <test>           Normal range lookup (e.g. sodium, troponin)
+reference.criteria <condition>    Diagnostic criteria (e.g. DKA, sepsis, PE)
+reference.drug_info <drug>        Drug mechanism, indications, contraindications
+interpret <test> <value>          Interpret a lab value against normal range
+```
+
+## Reward Design
+
+Dense rewards over the full trajectory. Every step can yield signal, not just the terminal action.
+
+| Task | Intermediate Budget | Terminal Budget | Total |
+|---|---|---|---|
+| Note Review | 0.10 (read note) | 0.90 (detection + correction quality) | 1.0 |
+| Calculation | 0.15 (read case + declare calculator) | 0.85 (numeric accuracy + correct calculator + efficiency) | 1.0 |
+| Diagnosis | 0.30 (chart exploration credit per relevant section) | 0.70 (diagnostic accuracy + workup completeness + efficiency + reasoning) | 1.0 |
+
+**Penalties:**
+- Protocol violations: -0.05 (imaging without vitals, confirming with <2 differentials, specialized labs without basic panels)
+- Duplicate tool calls: -0.05
+
+## Baseline Scores
+
+Model: `meta-llama/Llama-3.1-8B-Instruct` via HuggingFace Router (20 runs, random case per difficulty):
+
+| Task | Avg Score | Min | Max |
+|---|---|---|---|
+| Easy (note review) | 0.49 | 0.19 | 0.73 |
+| Medium (calculation) | 0.27 | 0.01 | 0.84 |
+| Hard (diagnosis) | 0.22 | 0.12 | 0.41 |
+
+`inference.py` produces the exact `[START]` / `[STEP]` / `[END]` stdout format required by OpenEnv and completes all 3 tasks in under 5 minutes on standard hardware.
+
+## Example Episode (Diagnosis - Hard)
+
+```
+> reset(options={"task": "hard"})
+Patient: 45M, presenting with fever, rash, and joint pain
+Type 'help' for available tools.
+
+> chart.history                                        reward: +0.02
+PMH: None significant
+Medications: None
+Social: Non-smoker, occasional alcohol
+
+> chart.vitals                                         reward: +0.02
+BP: 130/85 | HR: 102 | Temp: 39.2C | RR: 18 | SpO2: 98%
+
+> chart.labs                                           reward: 0.00
+Available lab panels: CBC, BMP, inflammatory_markers, LFTs
+
+> chart.labs inflammatory_markers                      reward: +0.02
+inflammatory_markers:
+  ESR: 85 mm/hr
+  CRP: 12.4 mg/dL
+  Ferritin: 26,250 ng/mL
+
+> reference.ranges ferritin                            reward: 0.00
+FERRITIN: Normal range 12-300 ng/mL
+  Female 12-150, Male 12-300. Very high in HLH, Still disease
+
+> interpret ferritin 26250                             reward: 0.00
+FERRITIN 26250.0 ng/mL: HIGH - critically elevated (normal 12-300)
+  Female 12-150, Male 12-300. Very high in HLH, Still disease
+
+> reference.criteria hlh                               reward: 0.00
+HLH (HScore): Fever, organomegaly, cytopenias (2-3 lineages),
+hypertriglyceridemia (>=265) or hypofibrinogenemia (<=150),
+ferritin >=500 (often >10,000), elevated soluble CD25...
+
+> ddx.add HLH                                         reward: 0.00
+Added 'HLH'. Differential has 1 entry(ies).
+
+> ddx.add Adult-onset Still disease                    reward: 0.00
+Added 'Adult-onset Still disease'. Differential has 2 entry(ies).
+
+> ddx.confirm Adult-onset Still disease                reward: +0.34
+Diagnosis submitted: 'Adult-onset Still disease'. Score: 0.34
+
+[STATUS] DDX: [HLH, Adult-onset Still disease] | Step: 10/50
+Total episode score: 0.40
+```
+
+The agent earned intermediate rewards for each relevant chart section explored (+0.02 each), used reference tools to interpret the critically elevated ferritin (no reward, but informed its reasoning), built a 2-item differential (avoiding the -0.05 penalty), and got partial terminal credit for a close but not exact diagnosis match.
+
+## Setup
+
+```bash
+# Install
+uv sync
+
+# Run server
+uv run uvicorn server.app:app --port 8000
+
+# Run inference (set HF_TOKEN first)
+export HF_TOKEN="your_token"
+uv run python inference.py
+```
+
+## Docker
+
+```bash
+docker build -t claude_code_for_health .
+docker run -p 8000:8000 claude_code_for_health
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `API_BASE_URL` | LLM endpoint | `https://router.huggingface.co/v1` |
+| `MODEL_NAME` | Model identifier | `meta-llama/Llama-3.1-8B-Instruct` |
+| `HF_TOKEN` | HuggingFace API key | (required) |
+| `IMAGE_NAME` | Docker image for `from_docker_image()` | (optional) |
+
+## Project Structure
+
+```
+claude_code_for_health/
+├── Dockerfile              # Container image definition
+├── openenv.yaml            # OpenEnv manifest
+├── pyproject.toml          # Dependencies
+├── inference.py            # Baseline inference script
+├── models.py               # MedAction, MedObservation, MedState
+├── client.py               # EnvClient wrapper
+├── __init__.py             # Module exports
+├── data/
+│   ├── MedCaseReasoning/   # Diagnosis cases (JSONL)
+│   ├── MedCalcBench/       # Calculation cases (CSV)
+│   ├── MEDEC/              # Note review cases (CSV)
+│   └── reference/          # Lab ranges, criteria, drug info (JSON)
+└── server/
+    ├── app.py              # FastAPI application
+    ├── claude_code_for_health_environment.py  # Core environment
+    ├── command_parser.py   # CLI command parsing
+    ├── data_loader.py      # Dataset loading
+    ├── task_configs.py     # Difficulty tiers + case selection
+    ├── graders.py          # Dense reward functions
+    ├── constants.py        # Reference data loader
+    └── ui.py               # Custom Gradio dashboard
+```

__init__.py

@@ -0,0 +1,9 @@
+from .client import ClaudeCodeForHealthEnv
+from .models import MedAction, MedObservation, MedState
+
+__all__ = [
+    "MedAction",
+    "MedObservation",
+    "MedState",
+    "ClaudeCodeForHealthEnv",
+]

client.py

@@ -0,0 +1,44 @@
+"""Client for the Claude Code for Health environment."""
+
+from typing import Dict
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from .models import MedAction, MedObservation, MedState
+
+
+class ClaudeCodeForHealthEnv(
+    EnvClient[MedAction, MedObservation, MedState]
+):
+    def _step_payload(self, action: MedAction) -> Dict:
+        return {"command": action.command}
+
+    def _parse_result(self, payload: Dict) -> StepResult[MedObservation]:
+        obs_data = payload.get("observation", {})
+        observation = MedObservation(
+            output=obs_data.get("output", ""),
+            error=obs_data.get("error", ""),
+            available_commands=obs_data.get("available_commands", []),
+            task_type=obs_data.get("task_type", ""),
+            step_number=obs_data.get("step_number", 0),
+            max_steps=obs_data.get("max_steps", 50),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=obs_data.get("metadata", {}),
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict) -> MedState:
+        return MedState(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+            task_type=payload.get("task_type", ""),
+            difficulty=payload.get("difficulty", "easy"),
+            total_score=payload.get("total_score", 0.0),
+            commands_issued=payload.get("commands_issued", 0),
+            is_submitted=payload.get("is_submitted", False),
+        )

data/MedCalcBench/train_data.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:503db8197c55438640e66bb8a20a114ef2d5e8c6a1b12b79ccd1aa9c3e33b2c1
+size 51145140

data/MedCaseReasoning/extraction_errors.jsonl

@@ -0,0 +1,2 @@
+{"pmcid": "PMC10399059", "error": "list index out of range", "final_diagnosis": "Streptococcus equi subspecies equi"}
+{"pmcid": "PMC6881760", "error": "Unterminated string starting at: line 145 column 7 (char 5668)", "final_diagnosis": "Intravascular large B-cell lymphoma"}

data/reference/diagnostic_criteria.json

@@ -0,0 +1,23 @@
+{
+  "dka": "DKA (Diabetic Ketoacidosis): pH <7.3, Serum bicarbonate <18 mEq/L, Blood glucose >250 mg/dL (or euglycemic if on SGLT2i), Positive serum/urine ketones, Anion gap >12. Severity: Mild (pH 7.25-7.30), Moderate (7.0-7.24), Severe (<7.0)",
+  "diabetic ketoacidosis": "DKA: pH <7.3, HCO3 <18, glucose >250, ketones positive, AG >12. Mild/Moderate/Severe by pH cutoffs 7.25/7.0",
+  "sepsis": "Sepsis (Sepsis-3): Suspected infection + SOFA score increase >=2. qSOFA (screening): >=2 of: RR >=22, altered mentation (GCS <15), SBP <=100 mmHg",
+  "sirs": "SIRS: >=2 of: Temp >38C or <36C, HR >90, RR >20 or PaCO2 <32, WBC >12k or <4k or >10% bands",
+  "pe": "Wells Criteria for PE: Clinical signs of DVT (+3), PE most likely (+3), HR >100 (+1.5), Immobilization/surgery (+1.5), Previous PE/DVT (+1.5), Hemoptysis (+1), Malignancy (+1). Low <2, Moderate 2-6, High >6",
+  "pulmonary embolism": "Wells Criteria: DVT signs (+3), PE most likely (+3), HR>100 (+1.5), immobilization (+1.5), prior PE/DVT (+1.5), hemoptysis (+1), cancer (+1). Score >4: consider CTPA",
+  "dvt": "Wells Criteria for DVT: Active cancer (+1), Paralysis/cast (+1), Bedridden >3d or surgery <12wk (+1), Tenderness along deep veins (+1), Entire leg swollen (+1), Calf >3cm (+1), Pitting edema (+1), Collateral veins (+1), Prior DVT (+1), Alternative dx as likely (-2). Low 0, Moderate 1-2, High >=3",
+  "heart failure": "Framingham Criteria for CHF: Major: PND, JVD, rales, cardiomegaly, S3, hepatojugular reflux, weight loss on diuretics. Minor: ankle edema, night cough, dyspnea on exertion, hepatomegaly, pleural effusion, HR>120. Diagnosis: 2 major OR 1 major + 2 minor",
+  "chf": "Framingham Criteria: 2 major criteria OR 1 major + 2 minor. BNP >400 supports dx. LVEF <40% = HFrEF, >=50% = HFpEF",
+  "mi": "STEMI: ST elevation >=1mm in >=2 contiguous leads (>=2mm in V1-V3). NSTEMI: Elevated troponin + ischemic symptoms without ST elevation. Type 1: plaque rupture. Type 2: demand ischemia",
+  "stroke": "NIH Stroke Scale for severity. CT head to rule out hemorrhage. tPA within 4.5h (NINDS criteria). Large vessel occlusion: consider thrombectomy within 24h",
+  "aki": "AKI (KDIGO): Stage 1: Cr increase >=0.3 mg/dL in 48h or 1.5-1.9x baseline. Stage 2: Cr 2.0-2.9x baseline. Stage 3: Cr >=3x baseline or Cr >=4.0 or initiation of RRT. Also UOP <0.5 mL/kg/h for 6h",
+  "ckd": "CKD: GFR <60 for >3 months. Stage 1: GFR>=90 (with kidney damage), Stage 2: 60-89, Stage 3a: 45-59, Stage 3b: 30-44, Stage 4: 15-29, Stage 5: <15",
+  "meningitis": "Bacterial meningitis: fever, nuchal rigidity, altered mental status (classic triad in ~44%). CSF: WBC >1000 (PMN predominant), protein >250, glucose <40 (or CSF/serum ratio <0.4), positive gram stain/culture. Kernig/Brudzinski signs. Empiric: ceftriaxone + vancomycin \u00b1 ampicillin (>50y or immunocompromised)",
+  "pancreatitis": "Acute pancreatitis: >=2 of 3: (1) Abdominal pain consistent with pancreatitis, (2) Serum lipase >=3x ULN, (3) Characteristic findings on imaging. Ranson criteria for severity. BISAP score for mortality",
+  "cirrhosis": "Child-Pugh Score: Bilirubin, Albumin, INR, Ascites, Encephalopathy. Class A: 5-6 (compensated), Class B: 7-9 (significant), Class C: 10-15 (decompensated). MELD for transplant prioritization",
+  "pneumonia": "CAP: CURB-65 for severity: Confusion, Urea >7, RR >=30, BP <90/60, Age >=65. Score 0-1: outpatient, 2: short stay, 3-5: ICU consideration. PSI/PORT score alternative",
+  "gout": "Gout: Monosodium urate crystals (needle-shaped, negatively birefringent). ACR/EULAR criteria: joint involvement, serum urate >6, acute episode features, tophi, imaging evidence",
+  "hlh": "HLH (HScore): Fever, organomegaly, cytopenias (2-3 lineages), hypertriglyceridemia (>=265) or hypofibrinogenemia (<=150), hemophagocytosis on biopsy, low/absent NK activity, ferritin >=500 (often >10,000), elevated soluble CD25",
+  "ards": "ARDS (Berlin Definition): Acute onset within 1 week, bilateral opacities on imaging, not fully explained by cardiac failure/fluid overload, PaO2/FiO2: Mild 200-300, Moderate 100-200, Severe <100 (with PEEP >=5)",
+  "dic": "DIC: Prolonged PT/PTT, low platelets, low fibrinogen, elevated D-dimer, schistocytes on smear. ISTH DIC score >=5 = overt DIC. Treat underlying cause. Acute (bleeding): replace factors. Chronic (clotting): anticoagulation"
+}

data/reference/drug_info.json

@@ -0,0 +1,21 @@
+{
+  "metformin": "Biguanide. Mechanism: Decreases hepatic glucose production, increases insulin sensitivity. Indications: Type 2 DM (first-line). Contraindications: eGFR <30, acute/chronic metabolic acidosis. Key: Hold before contrast, risk of lactic acidosis. Max 2550 mg/day",
+  "warfarin": "Vitamin K antagonist. Mechanism: Inhibits factors II, VII, IX, X and proteins C/S. Indications: AF, DVT/PE, mechanical valves. Monitoring: INR (target 2-3, or 2.5-3.5 for mechanical valves). Reversal: Vitamin K, FFP, PCC. Many drug/food interactions",
+  "heparin": "Unfractionated heparin. Mechanism: Potentiates antithrombin III, inhibits thrombin and factor Xa. Monitoring: aPTT (target 1.5-2.5x control). Reversal: protamine sulfate. Risk: HIT (check platelets). Weight-based dosing: 80 U/kg bolus, 18 U/kg/hr",
+  "enoxaparin": "LMWH. Mechanism: Anti-Xa > anti-IIa activity. Indications: DVT/PE treatment and prophylaxis. Dosing: Treatment 1 mg/kg BID or 1.5 mg/kg daily. Renal adjustment: CrCl <30 \u2192 1 mg/kg daily. Monitoring: Anti-Xa levels (trough 0.5-1.0). Partial reversal with protamine",
+  "aspirin": "NSAID/Antiplatelet. Mechanism: Irreversibly inhibits COX-1 \u2192 blocks TXA2. Indications: ACS, secondary prevention CVD, Kawasaki disease. Dose: 81mg (prevention), 325mg (acute ACS). Contraindications: Active bleeding, aspirin-exacerbated respiratory disease. Reye syndrome risk in children",
+  "clopidogrel": "P2Y12 inhibitor. Mechanism: Irreversibly blocks ADP receptor on platelets. Indications: ACS, PCI stenting (with aspirin), stroke prevention. Loading dose: 300-600mg. Maintenance: 75mg daily. CYP2C19 poor metabolizers: consider prasugrel or ticagrelor",
+  "lisinopril": "ACE inhibitor. Mechanism: Blocks ACE \u2192 decreases angiotensin II and aldosterone. Indications: HTN, HFrEF, post-MI, diabetic nephropathy. Contraindications: Bilateral renal artery stenosis, pregnancy, angioedema history. Monitor: K+, creatinine. Dry cough \u2192 switch to ARB",
+  "losartan": "ARB. Mechanism: Blocks AT1 receptor. Indications: HTN, diabetic nephropathy, HF (if ACE-intolerant). Contraindications: Pregnancy, bilateral renal artery stenosis. Advantage: No cough (unlike ACEi). Monitor K+, creatinine",
+  "amlodipine": "Calcium channel blocker (dihydropyridine). Mechanism: Blocks L-type Ca channels in vascular smooth muscle. Indications: HTN, angina. Side effects: Peripheral edema, flushing, headache. Does not affect HR significantly. Safe in HFrEF",
+  "metoprolol": "Beta-1 selective blocker. Mechanism: Blocks cardiac beta-1 receptors \u2192 decreased HR, contractility, BP. Indications: HTN, HFrEF (succinate), rate control AF, post-MI. Contraindications: Decompensated HF, severe bradycardia, 2nd/3rd degree AVB. Tartrate (BID) vs Succinate (daily, for HF)",
+  "carvedilol": "Non-selective beta + alpha-1 blocker. Mechanism: Beta blockade (negative chronotropy/inotropy) + alpha blockade (vasodilation). Indications: HFrEF (mortality benefit), HTN. Dose: Start 3.125mg BID, titrate to 25mg BID. Contraindications: Decompensated HF, reactive airway disease, severe bradycardia",
+  "furosemide": "Loop diuretic. Mechanism: Inhibits Na-K-2Cl cotransporter in thick ascending limb. Indications: Edema (HF, cirrhosis, nephrotic), HTN, acute pulmonary edema. IV:PO ratio 1:2. Monitor: K+, Mg2+, creatinine, uric acid. Ototoxicity at high doses",
+  "amoxicillin": "Aminopenicillin. Mechanism: Inhibits cell wall synthesis (PBP binding). Indications: Otitis media, sinusitis, UTI, H. pylori (triple therapy), dental infections. Spectrum: Strep, E. coli, H. influenzae. Resistance: beta-lactamase producers \u2192 add clavulanate",
+  "ceftriaxone": "3rd-gen cephalosporin. Mechanism: Inhibits cell wall synthesis. Indications: Meningitis, pneumonia, UTI, gonorrhea, Lyme disease. Spectrum: Broad gram-negative + some gram-positive. Crosses BBB. Do not mix with calcium-containing solutions (neonates). IM or IV",
+  "vancomycin": "Glycopeptide. Mechanism: Inhibits cell wall synthesis by binding D-Ala-D-Ala. Indications: MRSA, C. difficile (PO), endocarditis. Monitoring: Trough 15-20 mcg/mL (serious infections) or AUC/MIC. Toxicity: Red man syndrome (histamine, slow infusion), nephrotoxicity, ototoxicity",
+  "prednisone": "Glucocorticoid. Mechanism: Anti-inflammatory, immunosuppressive (NF-kB inhibition, decreased cytokines). Indications: Asthma exacerbation, autoimmune diseases, allergic reactions, adrenal insufficiency. Taper if >2 weeks use. Side effects: Hyperglycemia, osteoporosis, adrenal suppression, immunosuppression",
+  "insulin": "Hormone. Mechanism: Binds insulin receptor \u2192 glucose uptake, glycogen synthesis, lipogenesis. Types: Rapid (lispro, aspart), Short (regular), Intermediate (NPH), Long (glargine, detemir). DKA: IV regular insulin drip. Hypoglycemia is main risk. Sliding scale for inpatients",
+  "acetaminophen": "Analgesic/antipyretic. Mechanism: Central COX inhibition (not peripheral). Indications: Pain, fever. Max: 4g/day (2g/day in liver disease). Toxicity: Hepatotoxicity (NAPQI accumulation). Antidote: N-acetylcysteine (NAC). Rumack-Matthew nomogram for overdose",
+  "ibuprofen": "NSAID. Mechanism: Non-selective COX-1/COX-2 inhibitor. Indications: Pain, inflammation, fever. Contraindications: Active GI bleed, CKD stage 4-5, post-CABG, third trimester pregnancy. Risks: GI bleed, renal impairment, CV events. Max: 3200 mg/day"
+}

data/reference/lab_ranges.json

@@ -0,0 +1,350 @@
+{
+  "sodium": {
+    "low": 136,
+    "high": 145,
+    "unit": "mEq/L",
+    "context": "Hyponatremia <136, Hypernatremia >145"
+  },
+  "na": {
+    "low": 136,
+    "high": 145,
+    "unit": "mEq/L",
+    "context": "Hyponatremia <136, Hypernatremia >145"
+  },
+  "potassium": {
+    "low": 3.5,
+    "high": 5.0,
+    "unit": "mEq/L",
+    "context": "Hypokalemia <3.5, Hyperkalemia >5.0"
+  },
+  "k": {
+    "low": 3.5,
+    "high": 5.0,
+    "unit": "mEq/L",
+    "context": "Hypokalemia <3.5, Hyperkalemia >5.0"
+  },
+  "chloride": {
+    "low": 98,
+    "high": 106,
+    "unit": "mEq/L",
+    "context": ""
+  },
+  "cl": {
+    "low": 98,
+    "high": 106,
+    "unit": "mEq/L",
+    "context": ""
+  },
+  "bicarbonate": {
+    "low": 22,
+    "high": 29,
+    "unit": "mEq/L",
+    "context": "Metabolic acidosis <22, Metabolic alkalosis >29"
+  },
+  "hco3": {
+    "low": 22,
+    "high": 29,
+    "unit": "mEq/L",
+    "context": "Metabolic acidosis <22, Metabolic alkalosis >29"
+  },
+  "bun": {
+    "low": 7,
+    "high": 20,
+    "unit": "mg/dL",
+    "context": "Elevated in renal failure, dehydration, GI bleed"
+  },
+  "creatinine": {
+    "low": 0.7,
+    "high": 1.3,
+    "unit": "mg/dL",
+    "context": "Elevated in renal insufficiency. Use CKD-EPI or Cockcroft-Gault for GFR"
+  },
+  "glucose": {
+    "low": 70,
+    "high": 100,
+    "unit": "mg/dL",
+    "context": "Fasting. Diabetes: fasting >=126 or random >=200"
+  },
+  "calcium": {
+    "low": 8.5,
+    "high": 10.5,
+    "unit": "mg/dL",
+    "context": "Correct for albumin: add 0.8 per 1.0 below albumin 4.0"
+  },
+  "magnesium": {
+    "low": 1.7,
+    "high": 2.2,
+    "unit": "mg/dL",
+    "context": "Low Mg can cause refractory hypokalemia"
+  },
+  "phosphate": {
+    "low": 2.5,
+    "high": 4.5,
+    "unit": "mg/dL",
+    "context": ""
+  },
+  "albumin": {
+    "low": 3.5,
+    "high": 5.5,
+    "unit": "g/dL",
+    "context": "Low in liver disease, nephrotic syndrome, malnutrition"
+  },
+  "hemoglobin": {
+    "low": 12.0,
+    "high": 17.5,
+    "unit": "g/dL",
+    "context": "Female 12-16, Male 14-17.5. Anemia if below range"
+  },
+  "hgb": {
+    "low": 12.0,
+    "high": 17.5,
+    "unit": "g/dL",
+    "context": "Female 12-16, Male 14-17.5"
+  },
+  "hematocrit": {
+    "low": 36,
+    "high": 51,
+    "unit": "%",
+    "context": "Female 36-44, Male 41-51"
+  },
+  "hct": {
+    "low": 36,
+    "high": 51,
+    "unit": "%",
+    "context": "Female 36-44, Male 41-51"
+  },
+  "wbc": {
+    "low": 4.5,
+    "high": 11.0,
+    "unit": "x10^3/uL",
+    "context": "Leukocytosis >11, Leukopenia <4.5. Left shift if bands >10%"
+  },
+  "platelets": {
+    "low": 150,
+    "high": 400,
+    "unit": "x10^3/uL",
+    "context": "Thrombocytopenia <150, Thrombocytosis >400"
+  },
+  "plt": {
+    "low": 150,
+    "high": 400,
+    "unit": "x10^3/uL",
+    "context": "Thrombocytopenia <150, Thrombocytosis >400"
+  },
+  "inr": {
+    "low": 0.8,
+    "high": 1.2,
+    "unit": "",
+    "context": "Therapeutic on warfarin: 2.0-3.0. Mechanical valve: 2.5-3.5"
+  },
+  "pt": {
+    "low": 11,
+    "high": 13.5,
+    "unit": "seconds",
+    "context": "Prolonged in warfarin use, liver disease, DIC"
+  },
+  "ptt": {
+    "low": 25,
+    "high": 35,
+    "unit": "seconds",
+    "context": "Prolonged in heparin use, hemophilia, lupus anticoagulant"
+  },
+  "aptt": {
+    "low": 25,
+    "high": 35,
+    "unit": "seconds",
+    "context": "Same as PTT"
+  },
+  "fibrinogen": {
+    "low": 200,
+    "high": 400,
+    "unit": "mg/dL",
+    "context": "Low in DIC, liver failure. Acute phase reactant (rises in inflammation)"
+  },
+  "d-dimer": {
+    "low": 0,
+    "high": 0.5,
+    "unit": "mcg/mL FEU",
+    "context": "Elevated in PE, DVT, DIC, sepsis. High sensitivity, low specificity"
+  },
+  "troponin": {
+    "low": 0,
+    "high": 0.04,
+    "unit": "ng/mL",
+    "context": "Elevated in MI, myocarditis, PE, renal failure. High-sensitivity <14 ng/L"
+  },
+  "bnp": {
+    "low": 0,
+    "high": 100,
+    "unit": "pg/mL",
+    "context": "Heart failure: >400 likely, 100-400 gray zone. Age-adjusted: >age*50 if >75"
+  },
+  "nt-probnp": {
+    "low": 0,
+    "high": 300,
+    "unit": "pg/mL",
+    "context": "Age-dependent. HF likely: >900 (<50y), >1800 (50-75y), >1800 (>75y)"
+  },
+  "ast": {
+    "low": 10,
+    "high": 40,
+    "unit": "U/L",
+    "context": "Elevated in liver damage, MI, hemolysis. AST>ALT suggests alcoholic liver"
+  },
+  "alt": {
+    "low": 7,
+    "high": 56,
+    "unit": "U/L",
+    "context": "More specific for liver than AST. ALT>AST suggests viral/NASH"
+  },
+  "alp": {
+    "low": 44,
+    "high": 147,
+    "unit": "U/L",
+    "context": "Elevated in cholestasis, bone disease, pregnancy"
+  },
+  "bilirubin": {
+    "low": 0.1,
+    "high": 1.2,
+    "unit": "mg/dL",
+    "context": "Total. Direct >0.3 suggests conjugated/obstructive. Indirect: hemolysis, Gilbert"
+  },
+  "ggt": {
+    "low": 0,
+    "high": 51,
+    "unit": "U/L",
+    "context": "Elevated in cholestasis, alcohol use. Helps distinguish bone vs liver ALP"
+  },
+  "ldh": {
+    "low": 140,
+    "high": 280,
+    "unit": "U/L",
+    "context": "Elevated in hemolysis, tissue damage, lymphoma, PCP pneumonia"
+  },
+  "ferritin": {
+    "low": 12,
+    "high": 300,
+    "unit": "ng/mL",
+    "context": "Female 12-150, Male 12-300. Iron deficiency <12. Very high in HLH, Still disease"
+  },
+  "iron": {
+    "low": 60,
+    "high": 170,
+    "unit": "mcg/dL",
+    "context": "Low in iron deficiency, chronic disease. High in hemochromatosis"
+  },
+  "tibc": {
+    "low": 250,
+    "high": 370,
+    "unit": "mcg/dL",
+    "context": "High TIBC + low iron = iron deficiency. Low TIBC = chronic disease"
+  },
+  "transferrin saturation": {
+    "low": 20,
+    "high": 50,
+    "unit": "%",
+    "context": "Iron deficiency <20%. Hemochromatosis >45%"
+  },
+  "tsat": {
+    "low": 20,
+    "high": 50,
+    "unit": "%",
+    "context": "Iron deficiency <20%. Hemochromatosis >45%"
+  },
+  "crp": {
+    "low": 0,
+    "high": 1.0,
+    "unit": "mg/dL",
+    "context": "Acute phase reactant. >10 suggests bacterial infection"
+  },
+  "esr": {
+    "low": 0,
+    "high": 20,
+    "unit": "mm/hr",
+    "context": "Female 0-20, Male 0-15. Elevated in inflammation, infection, malignancy"
+  },
+  "procalcitonin": {
+    "low": 0,
+    "high": 0.1,
+    "unit": "ng/mL",
+    "context": ">0.5 suggests bacterial infection. >2.0 high risk sepsis"
+  },
+  "tsh": {
+    "low": 0.4,
+    "high": 4.0,
+    "unit": "mIU/L",
+    "context": "Hypothyroid >4.0, Hyperthyroid <0.4"
+  },
+  "free t4": {
+    "low": 0.8,
+    "high": 1.8,
+    "unit": "ng/dL",
+    "context": "Low in hypothyroid, High in hyperthyroid"
+  },
+  "hba1c": {
+    "low": 4.0,
+    "high": 5.6,
+    "unit": "%",
+    "context": "Pre-diabetes 5.7-6.4, Diabetes >=6.5"
+  },
+  "lactate": {
+    "low": 0.5,
+    "high": 2.0,
+    "unit": "mmol/L",
+    "context": "Elevated in sepsis, shock, ischemia. >4 = severe"
+  },
+  "ammonia": {
+    "low": 15,
+    "high": 45,
+    "unit": "mcg/dL",
+    "context": "Elevated in hepatic encephalopathy, urea cycle defects"
+  },
+  "lipase": {
+    "low": 0,
+    "high": 160,
+    "unit": "U/L",
+    "context": "Elevated in pancreatitis (>3x upper limit significant)"
+  },
+  "amylase": {
+    "low": 28,
+    "high": 100,
+    "unit": "U/L",
+    "context": "Less specific than lipase for pancreatitis"
+  },
+  "uric acid": {
+    "low": 3.0,
+    "high": 7.0,
+    "unit": "mg/dL",
+    "context": "Gout risk >7.0. Tumor lysis syndrome causes acute elevation"
+  },
+  "ph": {
+    "low": 7.35,
+    "high": 7.45,
+    "unit": "",
+    "context": "Acidemia <7.35, Alkalemia >7.45"
+  },
+  "pco2": {
+    "low": 35,
+    "high": 45,
+    "unit": "mmHg",
+    "context": "Respiratory acidosis >45, Respiratory alkalosis <35"
+  },
+  "po2": {
+    "low": 80,
+    "high": 100,
+    "unit": "mmHg",
+    "context": "Hypoxemia <80. Critical <60"
+  },
+  "spo2": {
+    "low": 95,
+    "high": 100,
+    "unit": "%",
+    "context": "Hypoxemia <95%. Critical <90%"
+  },
+  "anion gap": {
+    "low": 8,
+    "high": 12,
+    "unit": "mEq/L",
+    "context": "Elevated: MUDPILES (Methanol, Uremia, DKA, Propylene glycol, INH/Iron, Lactic acidosis, Ethylene glycol, Salicylates)"
+  }
+}

inference.py

@@ -0,0 +1,202 @@
+"""
+Baseline inference script for Claude Code for Health.
+
+Runs an LLM agent against all 3 task difficulties (easy, medium, hard).
+Emits [START], [STEP], [END] stdout lines per the OpenEnv spec.
+
+Required env vars:
+    API_BASE_URL  — LLM endpoint (default: HF router)
+    MODEL_NAME    — model identifier
+    HF_TOKEN      — API key
+"""
+
+import asyncio
+import os
+import re
+import sys
+import textwrap
+from typing import Optional
+
+from openai import OpenAI
+
+from claude_code_for_health import ClaudeCodeForHealthEnv, MedAction
+
+
+IMAGE_NAME = os.getenv("LOCAL_IMAGE_NAME") or os.getenv("IMAGE_NAME")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+if not API_KEY:
+    raise ValueError("HF_TOKEN environment variable is required")
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+MODEL_NAME = os.getenv("MODEL_NAME") or "meta-llama/Llama-3.1-8B-Instruct"
+BENCHMARK = "claude_code_for_health"
+MAX_STEPS = 30
+TEMPERATURE = 0.0
+MAX_TOKENS = 200
+
+SYSTEM_PROMPT = textwrap.dedent("""\
+    You are a clinical AI assistant interacting with a medical environment via CLI commands.
+    Each turn, respond with EXACTLY ONE command — no explanation, no markdown, just the command.
+
+    DIAGNOSIS TASKS — commands:
+      chart.history          View past medical history, meds, allergies, social, family
+      chart.vitals           View vital signs
+      chart.labs             List available lab panels
+      chart.labs <panel>     View specific lab panel results
+      chart.imaging          List available imaging studies
+      chart.imaging <type>   View specific imaging findings
+      chart.exam             List available physical exam systems
+      chart.exam <system>    View specific exam findings
+      chart.medications      View current medications
+      chart.allergies        View known allergies
+      ddx.add <diagnosis>    Add diagnosis to differential
+      ddx.remove <diagnosis> Remove from differential
+      ddx.list               Show current differential
+      ddx.confirm <diagnosis> Submit final diagnosis (ends episode)
+      help                   List commands
+
+    CALCULATION TASKS — commands:
+      case.read              Read the full patient note
+      calculate <name>       Declare which calculator you're using
+      submit <number>        Submit numeric answer (ends episode)
+      help                   List commands
+
+    NOTE REVIEW TASKS — commands:
+      note.read                              Read the clinical note
+      note.correct <sentence_id> <text>      Correct an error in a sentence
+      note.approve                           Approve note / submit corrections (ends episode)
+      help                                   List commands
+
+    REFERENCE TOOLS (available in all tasks):
+      reference.ranges <test>          Look up normal range for a lab test
+      reference.criteria <condition>   Look up diagnostic criteria for a condition
+      reference.drug_info <drug>       Look up drug mechanism, indications, contraindications
+      interpret <test> <value>         Interpret a lab value (e.g. interpret sodium 128)
+
+    Strategy:
+    - Always read available data before making decisions
+    - Use reference tools when unsure about normal ranges or diagnostic criteria
+    - For diagnosis: review history, vitals, labs, then form differential before confirming
+    - For calculations: read the case, identify the calculator, compute, submit
+    - For note review: read the note carefully, correct errors if any, then approve
+""")
+
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error if error else "null"
+    done_val = str(done).lower()
+    action_clean = action.replace("\n", " ").strip()
+    print(
+        f"[STEP] step={step} action={action_clean} reward={reward:.2f} done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(success: bool, steps: int, score: float, rewards: list[float]) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    print(
+        f"[END] success={str(success).lower()} steps={steps} score={score:.2f} rewards={rewards_str}",
+        flush=True,
+    )
+
+
+def clean_llm_output(text: str) -> str:
+    text = text.strip()
+    text = re.sub(r"^```\w*\n?", "", text)
+    text = re.sub(r"\n?```$", "", text)
+    text = text.strip("`").strip()
+    if text.startswith("$ "):
+        text = text[2:]
+    lines = text.strip().split("\n")
+    return lines[0].strip()
+
+
+def get_agent_command(client: OpenAI, messages: list[dict]) -> str:
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=messages,
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        raw = (completion.choices[0].message.content or "").strip()
+        return clean_llm_output(raw) if raw else "help"
+    except Exception as exc:
+        print(f"[DEBUG] LLM request failed: {exc}", file=sys.stderr, flush=True)
+        return "help"
+
+
+async def run_task(client: OpenAI, env, difficulty: str) -> float:
+    rewards: list[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+
+    log_start(task=difficulty, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        result = await env.reset(options={"task": difficulty})
+        observation_text = result.observation.output
+        task_type = result.observation.task_type
+
+        messages = [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": f"Task type: {task_type}\n\nEnvironment output:\n{observation_text}"},
+        ]
+
+        for step in range(1, MAX_STEPS + 1):
+            if result.done:
+                break
+
+            command = get_agent_command(client, messages)
+
+            messages.append({"role": "assistant", "content": command})
+
+            result = await env.step(MedAction(command=command))
+
+            reward = result.reward or 0.0
+            done = result.done
+            error = result.observation.error or None
+            observation_text = result.observation.output
+
+            rewards.append(reward)
+            steps_taken = step
+
+            messages.append({"role": "user", "content": f"Environment output:\n{observation_text}"})
+
+            log_step(step=step, action=command, reward=reward, done=done, error=error)
+
+            if done:
+                break
+
+        score = sum(rewards)
+        score = min(max(score, 0.01), 0.99)
+        success = score >= 0.5
+
+    finally:
+        try:
+            await env.close()
+        except Exception as e:
+            print(f"[DEBUG] env.close() error: {e}", file=sys.stderr, flush=True)
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards)
+
+    return score
+
+
+async def main() -> None:
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY)
+
+    for difficulty in ["easy", "medium", "hard"]:
+        if IMAGE_NAME:
+            env = await ClaudeCodeForHealthEnv.from_docker_image(IMAGE_NAME)
+        else:
+            env = ClaudeCodeForHealthEnv(base_url=os.getenv("ENV_BASE_URL", "http://localhost:8000"))
+        await run_task(client, env, difficulty)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,38 @@
+"""
+Data models for the Claude Code for Health Environment.
+
+Three Pydantic models defining the action/observation/state contract:
+- MedAction: single CLI command string (terminal metaphor)
+- MedObservation: command output + episode metadata
+- MedState: episode tracking for state() endpoint
+"""
+
+from openenv.core.env_server.types import Action, Observation, State
+from pydantic import Field
+
+
+class MedAction(Action):
+    """Agent sends a single CLI command string per step."""
+
+    command: str = Field(..., description="CLI command string, e.g. 'chart.labs CBC'")
+
+
+class MedObservation(Observation):
+    """Environment returns command output and episode context."""
+
+    output: str = Field(default="", description="Command output text")
+    error: str = Field(default="", description="Error message if command invalid")
+    available_commands: list[str] = Field(default_factory=list)
+    task_type: str = Field(default="", description="diagnosis | calculation | note_review")
+    step_number: int = Field(default=0)
+    max_steps: int = Field(default=50)
+
+
+class MedState(State):
+    """Episode state exposed via the state() endpoint."""
+
+    task_type: str = Field(default="")
+    difficulty: str = Field(default="easy")
+    total_score: float = Field(default=0.0)
+    commands_issued: int = Field(default=0)
+    is_submitted: bool = Field(default=False)

openenv.yaml

@@ -0,0 +1,24 @@
+spec_version: 1
+name: claude_code_for_health
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+
+description: >
+  Clinical terminal environment where an AI agent works through medical tasks
+  by typing CLI commands. Three task types: diagnostic workup, medical
+  calculations, and clinical note review. All programmatically graded.
+
+tasks:
+  - name: easy
+    description: "Clinical note review — identify if a note is error-free or fix obvious errors"
+    difficulty: easy
+
+  - name: medium
+    description: "Medical calculation — read a clinical scenario, identify the formula, compute the answer"
+    difficulty: medium
+
+  - name: hard
+    description: "Diagnostic workup — explore patient chart via CLI, build differential, confirm diagnosis"
+    difficulty: hard

pyproject.toml

@@ -0,0 +1,38 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-claude_code_for_health"
+version = "0.1.0"
+description = "Claude Code For Health environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    "rapidfuzz>=3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m claude_code_for_health.server.app
+server = "claude_code_for_health.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["claude_code_for_health", "claude_code_for_health.server"]
+package-dir = { "claude_code_for_health" = ".", "claude_code_for_health.server" = "server" }

server/__init__.py

@@ -0,0 +1,3 @@
+from .claude_code_for_health_environment import ClaudeCodeForHealthEnvironment
+
+__all__ = ["ClaudeCodeForHealthEnvironment"]

server/app.py

@@ -0,0 +1,33 @@
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:
+    raise ImportError(
+        "openenv is required. Install with: pip install openenv-core[core]"
+    ) from e
+
+try:
+    from ..models import MedAction, MedObservation
+    from .claude_code_for_health_environment import ClaudeCodeForHealthEnvironment
+    from .ui import build_custom_dashboard
+except (ImportError, ModuleNotFoundError):
+    from models import MedAction, MedObservation
+    from server.claude_code_for_health_environment import ClaudeCodeForHealthEnvironment
+    from server.ui import build_custom_dashboard
+
+app = create_app(
+    ClaudeCodeForHealthEnvironment,
+    MedAction,
+    MedObservation,
+    env_name="claude_code_for_health",
+    max_concurrent_envs=1,
+    gradio_builder=build_custom_dashboard,
+)
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

server/claude_code_for_health_environment.py

@@ -0,0 +1,588 @@
+"""Core environment: reset/step/state for all three clinical task types."""
+
+from random import Random
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+
+try:
+    from ..models import MedAction, MedObservation, MedState
+except ImportError:
+    from models import MedAction, MedObservation, MedState
+
+from . import command_parser, constants, graders, task_configs
+from .data_loader import DataLoader
+
+PROTOCOL_PENALTY = -0.05
+SPECIALIZED_LAB_PANELS = {"abg", "coags", "coagulation", "cultures", "cytology"}
+
+REFERENCE_TOOLS = [
+    "reference.ranges <test>", "reference.criteria <condition>",
+    "reference.drug_info <drug>", "interpret <test> <value>",
+]
+REFERENCE_TOOL_NAMES = {"reference.ranges", "reference.criteria", "reference.drug_info", "interpret"}
+
+TASK_TOOLS = {
+    "diagnosis": [
+        "chart.history", "chart.vitals", "chart.labs [panel]",
+        "chart.imaging [type]", "chart.exam [system]",
+        "chart.medications", "chart.allergies",
+        "ddx.list", "ddx.add <diagnosis>", "ddx.remove <diagnosis>",
+        "ddx.confirm <diagnosis>", "help",
+    ] + REFERENCE_TOOLS,
+    "calculation": [
+        "case.read", "calculate <calculator_name>",
+        "submit <numeric_value>", "help",
+    ] + REFERENCE_TOOLS,
+    "note_review": [
+        "note.read", "note.correct <sentence_id> <corrected_text>",
+        "note.approve", "help",
+    ] + REFERENCE_TOOLS,
+}
+
+VALID_TOOL_NAMES = {
+    "diagnosis": {
+        "chart.history", "chart.vitals", "chart.labs", "chart.imaging",
+        "chart.exam", "chart.medications", "chart.allergies",
+        "ddx.list", "ddx.add", "ddx.remove", "ddx.confirm", "help",
+    } | REFERENCE_TOOL_NAMES,
+    "calculation": {"case.read", "calculate", "submit", "help"} | REFERENCE_TOOL_NAMES,
+    "note_review": {"note.read", "note.correct", "note.approve", "help"} | REFERENCE_TOOL_NAMES,
+}
+
+
+class ClaudeCodeForHealthEnvironment(Environment):
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self):
+        self._data_loader = DataLoader()
+        self._rng = Random()
+        self._state = MedState(episode_id=str(uuid4()), step_count=0)
+        self._max_steps = 50
+        self._reset_episode_vars()
+
+    def _reset_episode_vars(self):
+        self._task_type = ""
+        self._difficulty = "easy"
+        self._task_data: dict = {}
+        self._ground_truth: dict = {}
+        self._agent_actions: list[str] = []
+        self._ddx_list: list[str] = []
+        self._confirmed_diagnosis = ""
+        self._calculator_used = ""
+        self._submitted_value: float | None = None
+        self._corrections: dict[str, str] = {}
+        self._accessed_sections: set[str] = set()
+        self._relevant_sections: set[str] = set()
+        self._case_read = False
+        self._note_read = False
+        self._calculator_declared = False
+        self._is_done = False
+        self._cumulative_reward = 0.0
+        self._seen_commands: set[str] = set()
+
+    # ------------------------------------------------------------------
+    # reset / step / state
+    # ------------------------------------------------------------------
+
+    def reset(self, *, seed=None, options=None) -> MedObservation:
+        self._data_loader.load_all()
+        if seed is not None:
+            self._rng = Random(seed)
+
+        opts = options or {}
+        self._difficulty = opts.get("task", "easy")
+        self._task_type = opts.get("task_type") or task_configs.get_default_task_type(self._difficulty, self._rng)
+
+        cases_map = {
+            "diagnosis": self._data_loader.get_diagnosis_cases,
+            "calculation": self._data_loader.get_calculation_cases,
+            "note_review": self._data_loader.get_note_cases,
+        }
+        cases = cases_map.get(self._task_type, self._data_loader.get_diagnosis_cases)()
+        case = task_configs.select_case(self._task_type, self._difficulty, cases, self._rng)
+
+        self._state = MedState(
+            episode_id=str(uuid4()),
+            step_count=0,
+            task_type=self._task_type,
+            difficulty=self._difficulty,
+        )
+        self._reset_episode_vars()
+        self._task_type = self._state.task_type
+        self._difficulty = self._state.difficulty
+        self._task_data = case
+        self._setup_ground_truth(case)
+
+        if self._task_type == "diagnosis":
+            self._relevant_sections = graders.compute_relevant_sections(case.get("extracted", {}))
+
+        return MedObservation(
+            output=self._build_initial_observation(case),
+            available_commands=TASK_TOOLS.get(self._task_type, ["help"]),
+            task_type=self._task_type,
+            step_number=0,
+            max_steps=self._max_steps,
+            done=False,
+            reward=0.0,
+        )
+
+    def step(self, action: MedAction) -> MedObservation:
+        if self._is_done:
+            return self._obs("Episode is over. Call reset() to start a new one.", reward=0.0, done=True)
+
+        self._state.step_count += 1
+        self._state.commands_issued += 1
+        raw = action.command
+        self._agent_actions.append(raw)
+
+        cmd, args = command_parser.parse(raw)
+
+        if not cmd:
+            return self._obs("Empty command. Type 'help' for available tools.", reward=0.0)
+
+        valid = VALID_TOOL_NAMES.get(self._task_type, {"help"})
+        if cmd not in valid:
+            return self._obs(
+                f"Unknown tool: '{cmd}'. Type 'help' for available tools.",
+                error=f"Unknown command: {cmd}",
+                reward=0.0,
+            )
+
+        full_cmd = raw.strip().lower()
+        is_duplicate = full_cmd in self._seen_commands and cmd not in ("help", "ddx.list")
+        self._seen_commands.add(full_cmd)
+
+        output, reward, done = self._dispatch(cmd, args)
+
+        if is_duplicate and not done:
+            output += f"\n[NOTE] Duplicate tool call. Efficiency penalty: {PROTOCOL_PENALTY}"
+            reward += PROTOCOL_PENALTY
+
+        self._cumulative_reward += reward
+        self._state.total_score = round(self._cumulative_reward, 4)
+
+        if done:
+            self._is_done = True
+            self._state.is_submitted = True
+
+        if not done and self._state.step_count >= self._max_steps:
+            terminal_reward = self._force_terminal()
+            reward += terminal_reward
+            self._cumulative_reward += terminal_reward
+            self._state.total_score = round(self._cumulative_reward, 4)
+            done = True
+            self._is_done = True
+            output += "\n\nMax steps reached. Episode ended."
+
+        return self._obs(output, reward=round(reward, 4), done=done)
+
+    @property
+    def state(self) -> MedState:
+        return self._state
+
+    # ------------------------------------------------------------------
+    # Command dispatch
+    # ------------------------------------------------------------------
+
+    def _dispatch(self, cmd: str, args: list[str]) -> tuple[str, float, bool]:
+        if cmd == "help":
+            return self._handle_help(), 0.0, False
+
+        ref_result = self._dispatch_reference(cmd, args)
+        if ref_result is not None:
+            return ref_result
+
+        dispatch_map = {
+            "diagnosis": self._dispatch_diagnosis,
+            "calculation": self._dispatch_calculation,
+            "note_review": self._dispatch_note,
+        }
+        handler = dispatch_map.get(self._task_type)
+        if handler:
+            return handler(cmd, args)
+        return "Internal error: unknown task type.", 0.0, False
+
+    def _dispatch_reference(self, cmd: str, args: list[str]) -> tuple[str, float, bool] | None:
+        lookup_map = {
+            "reference.ranges": ("test_name", constants.lookup_range),
+            "reference.criteria": ("condition", constants.lookup_criteria),
+            "reference.drug_info": ("drug_name", constants.lookup_drug),
+        }
+        if cmd in lookup_map:
+            param_name, lookup_fn = lookup_map[cmd]
+            if not args:
+                return f"Usage: {cmd} <{param_name}>", 0.0, False
+            result = lookup_fn(args[0])
+            if result is None:
+                return f"No results found for '{args[0]}'.", 0.0, False
+            return result, 0.0, False
+
+        if cmd == "interpret":
+            if not args:
+                return "Usage: interpret <test_name> <value>", 0.0, False
+            parts = args[0].rsplit(None, 1) if len(args) == 1 else args
+            if len(parts) < 2:
+                return "Usage: interpret <test_name> <value>", 0.0, False
+            result = constants.interpret_value(parts[0], parts[-1])
+            if result is None:
+                return f"Unknown test '{parts[0]}'. Try: sodium, potassium, troponin, wbc, etc.", 0.0, False
+            return result, 0.0, False
+
+        return None
+
+    # ------------------------------------------------------------------
+    # Diagnosis tools
+    # ------------------------------------------------------------------
+
+    def _diag_step_reward(self, cmd: str, args: list[str]) -> float:
+        return graders.diagnosis_step_reward(cmd, args, self._accessed_sections, self._relevant_sections)
+
+    def _handle_chart_keyed(self, data: dict, key_arg: str | None, cmd: str,
+                            label: str, list_label: str) -> tuple[str, float, bool]:
+        if not key_arg:
+            keys = list(data.keys()) if data else []
+            if keys:
+                return f"Available {list_label}: {', '.join(keys)}", 0.0, False
+            return f"No {list_label} available.", 0.0, False
+
+        matched = self._fuzzy_key_match(key_arg, data)
+        if matched is None:
+            return f"{label} '{key_arg}' not available. Use '{cmd}' to list.", 0.0, False
+
+        value = data[matched]
+        output = self._format_dict(value, title=matched) if isinstance(value, dict) else f"{matched}: {value}"
+        reward = self._diag_step_reward(cmd, [matched.lower()])
+        return output, reward, False
+
+    def _dispatch_diagnosis(self, cmd: str, args: list[str]) -> tuple[str, float, bool]:
+        extracted = self._task_data.get("extracted", {})
+        penalty, warning = self._check_prerequisites(cmd, args)
+
+        if cmd == "chart.history":
+            output = self._format_history(extracted.get("history", {}))
+            return (output + warning), self._diag_step_reward(cmd, args) + penalty, False
+
+        if cmd == "chart.vitals":
+            output = self._format_vitals(extracted.get("vitals", {}))
+            return (output + warning), self._diag_step_reward(cmd, args) + penalty, False
+
+        if cmd == "chart.labs":
+            output, reward, done = self._handle_chart_keyed(
+                extracted.get("labs", {}), args[0] if args else None,
+                "chart.labs", "Lab panel", "lab panels")
+            return (output + warning), reward + penalty, done
+
+        if cmd == "chart.imaging":
+            output, reward, done = self._handle_chart_keyed(
+                extracted.get("imaging", {}), args[0] if args else None,
+                "chart.imaging", "Imaging", "imaging")
+            return (output + warning), reward + penalty, done
+
+        if cmd == "chart.exam":
+            output, reward, done = self._handle_chart_keyed(
+                extracted.get("physical_exam", {}), args[0] if args else None,
+                "chart.exam", "Exam", "exam systems")
+            return output, reward, done
+
+        if cmd == "chart.medications":
+            meds = extracted.get("history", {}).get("medications", [])
+            return ("Medications: " + ", ".join(meds)) if meds else "No medications listed.", 0.0, False
+
+        if cmd == "chart.allergies":
+            allergies = extracted.get("history", {}).get("allergies", [])
+            return ("Allergies: " + ", ".join(allergies)) if allergies else "No known allergies.", 0.0, False
+
+        if cmd == "ddx.list":
+            if self._ddx_list:
+                items = "\n".join(f"  {i+1}. {d}" for i, d in enumerate(self._ddx_list))
+                return f"Current differential:\n{items}", 0.0, False
+            return "Differential is empty.", 0.0, False
+
+        if cmd == "ddx.add":
+            if not args:
+                return "Usage: ddx.add <diagnosis>", 0.0, False
+            dx = args[0].strip()
+            self._ddx_list.append(dx)
+            return f"Added '{dx}'. Differential has {len(self._ddx_list)} entry(ies).", 0.0, False
+
+        if cmd == "ddx.remove":
+            if not args:
+                return "Usage: ddx.remove <diagnosis>", 0.0, False
+            dx = args[0].strip().lower()
+            before = len(self._ddx_list)
+            self._ddx_list = [d for d in self._ddx_list if d.lower() != dx]
+            if len(self._ddx_list) < before:
+                return f"Removed. Differential has {len(self._ddx_list)} entry(ies).", 0.0, False
+            return f"'{args[0]}' not found in differential.", 0.0, False
+
+        if cmd == "ddx.confirm":
+            if not args:
+                return "Usage: ddx.confirm <diagnosis>", 0.0, False
+            self._confirmed_diagnosis = args[0].strip()
+            terminal = graders.diagnosis_terminal_reward(
+                confirmed=self._confirmed_diagnosis,
+                ground_truth_diagnosis=self._ground_truth.get("diagnosis", ""),
+                accessed_sections=self._accessed_sections,
+                relevant_sections=self._relevant_sections,
+                ddx_list=self._ddx_list,
+                steps_taken=self._state.step_count,
+            ) + penalty
+            return f"Diagnosis submitted: '{self._confirmed_diagnosis}'. Score: {terminal:.2f}" + warning, terminal, True
+
+        return f"Unknown diagnosis tool: {cmd}", 0.0, False
+
+    # ------------------------------------------------------------------
+    # Calculation tools
+    # ------------------------------------------------------------------
+
+    def _dispatch_calculation(self, cmd: str, args: list[str]) -> tuple[str, float, bool]:
+        if cmd == "case.read":
+            note = self._task_data.get("Patient Note", "No patient note available.")
+            question = self._task_data.get("Question", "")
+            output = note + (f"\n\nQuestion: {question}" if question else "")
+            reward = graders.calculation_step_reward(cmd, self._case_read, self._calculator_declared)
+            self._case_read = True
+            return output, reward, False
+
+        if cmd == "calculate":
+            if not args:
+                return "Usage: calculate <calculator_name>", 0.0, False
+            self._calculator_used = args[0].strip()
+            reward = graders.calculation_step_reward("calculate", self._case_read, self._calculator_declared)
+            self._calculator_declared = True
+            return f"Calculator noted: {self._calculator_used}. Use 'submit <value>' with your answer.", reward, False
+
+        if cmd == "submit":
+            if not args:
+                return "Usage: submit <numeric_value>", 0.0, False
+            try:
+                self._submitted_value = float(args[0].strip())
+            except ValueError:
+                return f"Cannot parse '{args[0]}' as a number.", 0.0, False
+
+            gt = self._ground_truth
+            try:
+                gt_answer = float(gt.get("answer", 0))
+                lower = float(gt.get("lower_limit", gt_answer))
+                upper = float(gt.get("upper_limit", gt_answer))
+            except (ValueError, TypeError):
+                gt_answer, lower, upper = 0.0, 0.0, 0.0
+
+            terminal = graders.calculation_terminal_reward(
+                submitted_value=self._submitted_value,
+                ground_truth=gt_answer,
+                lower_limit=lower,
+                upper_limit=upper,
+                calculator_used=self._calculator_used,
+                expected_calculator=gt.get("calculator_name", ""),
+                steps_taken=self._state.step_count,
+            )
+            return f"Submitted: {self._submitted_value}. Score: {terminal:.2f}", terminal, True
+
+        return f"Unknown calculation tool: {cmd}", 0.0, False
+
+    # ------------------------------------------------------------------
+    # Note review tools
+    # ------------------------------------------------------------------
+
+    def _dispatch_note(self, cmd: str, args: list[str]) -> tuple[str, float, bool]:
+        if cmd == "note.read":
+            sentences_raw = self._task_data.get("Sentences", "")
+            output = self._format_note_sentences(sentences_raw) if sentences_raw else self._task_data.get("Text", "No note available.")
+            reward = graders.note_step_reward(cmd, self._note_read)
+            self._note_read = True
+            return output, reward, False
+
+        if cmd == "note.correct":
+            if len(args) < 2:
+                return "Usage: note.correct <sentence_id> <corrected_text>", 0.0, False
+            self._corrections[args[0].strip()] = args[1].strip()
+            return f"Correction recorded for sentence {args[0].strip()}.", 0.0, False
+
+        if cmd == "note.approve":
+            gt = self._ground_truth
+            terminal = graders.note_terminal_reward(
+                corrections=self._corrections,
+                has_error=bool(gt.get("has_error", False)),
+                error_sentence_id=gt.get("error_sentence_id"),
+                corrected_sentence=gt.get("corrected_sentence"),
+            )
+            status = "Corrections submitted." if self._corrections else "Note approved as correct."
+            return f"{status} Score: {terminal:.2f}", terminal, True
+
+        return f"Unknown note review tool: {cmd}", 0.0, False
+
+    # ------------------------------------------------------------------
+    # Setup helpers
+    # ------------------------------------------------------------------
+
+    def _setup_ground_truth(self, case: dict):
+        if self._task_type == "diagnosis":
+            extracted = case.get("extracted", {})
+            gt = extracted.get("ground_truth", {})
+            self._ground_truth = {
+                "diagnosis": gt.get("diagnosis", case.get("final_diagnosis", "")),
+                "organ_system": gt.get("organ_system", ""),
+                "key_findings": gt.get("key_findings", []),
+            }
+        elif self._task_type == "calculation":
+            self._ground_truth = {
+                "answer": case.get("Ground Truth Answer", "0"),
+                "lower_limit": case.get("Lower Limit", case.get("Ground Truth Answer", "0")),
+                "upper_limit": case.get("Upper Limit", case.get("Ground Truth Answer", "0")),
+                "calculator_name": case.get("Calculator Name", ""),
+                "explanation": case.get("Ground Truth Explanation", ""),
+            }
+        elif self._task_type == "note_review":
+            try:
+                has_error = int(float(case.get("Error Flag", 0))) == 1
+            except (ValueError, TypeError):
+                has_error = False
+            self._ground_truth = {
+                "has_error": has_error,
+                "error_sentence_id": str(case.get("Error Sentence ID", "")).strip() if has_error else None,
+                "error_sentence": case.get("Error Sentence", "") if has_error else None,
+                "corrected_sentence": case.get("Corrected Sentence", "") if has_error else None,
+            }
+
+    def _build_initial_observation(self, case: dict) -> str:
+        if self._task_type == "diagnosis":
+            extracted = case.get("extracted", {})
+            demo = extracted.get("demographics", {})
+            cc = extracted.get("chief_complaint", case.get("case_prompt", "")[:150])
+            return f"Patient: {demo.get('age', '?')}{demo.get('sex', '?')}, {cc}\nType 'help' for available tools."
+        elif self._task_type == "calculation":
+            return (
+                f"Medical Calculation Task — {case.get('Calculator Name', '')}\n"
+                f"{case.get('Question', '')}\n"
+                f"Type 'case.read' to view the full patient note."
+            )
+        elif self._task_type == "note_review":
+            return "Clinical Note Review Task\nReview the note for medical errors. Correct any you find, then approve.\nType 'note.read' to view the clinical note."
+        return "Unknown task type."
+
+    def _handle_help(self) -> str:
+        tools = TASK_TOOLS.get(self._task_type, ["help"])
+        lines = [f"Available tools ({self._task_type}):"]
+        for t in tools:
+            lines.append(f"  {t}")
+        return "\n".join(lines)
+
+    def _force_terminal(self) -> float:
+        if self._task_type == "diagnosis":
+            return graders.diagnosis_terminal_reward(
+                confirmed=self._confirmed_diagnosis or "",
+                ground_truth_diagnosis=self._ground_truth.get("diagnosis", ""),
+                accessed_sections=self._accessed_sections,
+                relevant_sections=self._relevant_sections,
+                ddx_list=self._ddx_list,
+                steps_taken=self._state.step_count,
+            )
+        elif self._task_type == "note_review":
+            return graders.note_terminal_reward(
+                corrections=self._corrections,
+                has_error=bool(self._ground_truth.get("has_error", False)),
+                error_sentence_id=self._ground_truth.get("error_sentence_id"),
+                corrected_sentence=self._ground_truth.get("corrected_sentence"),
+            )
+        return 0.0
+
+    def _check_prerequisites(self, cmd: str, args: list[str]) -> tuple[float, str]:
+        if cmd == "chart.imaging" and args:
+            if "vitals" not in self._accessed_sections:
+                return PROTOCOL_PENALTY, f"\n[WARNING] Ordering imaging without baseline vitals: {PROTOCOL_PENALTY} protocol penalty"
+
+        if cmd == "chart.labs" and args:
+            if args[0].lower() in SPECIALIZED_LAB_PANELS:
+                has_basic = any(s.startswith("labs.") and s.split(".")[-1] in ("cbc", "bmp") for s in self._accessed_sections)
+                if not has_basic:
+                    return PROTOCOL_PENALTY, f"\n[WARNING] Ordering specialized labs without basic panels (CBC/BMP): {PROTOCOL_PENALTY} protocol penalty"
+
+        if cmd == "ddx.confirm" and len(self._ddx_list) < 2:
+            return PROTOCOL_PENALTY, f"\n[WARNING] Confirming diagnosis with <2 differentials: {PROTOCOL_PENALTY} protocol penalty"
+
+        return 0.0, ""
+
+    # ------------------------------------------------------------------
+    # Observation + status
+    # ------------------------------------------------------------------
+
+    def _obs(self, output: str, reward: float = 0.0, done: bool = False, error: str = "") -> MedObservation:
+        if not done and self._task_type:
+            output = output + "\n\n" + self._status_footer()
+        return MedObservation(
+            output=output,
+            error=error,
+            available_commands=TASK_TOOLS.get(self._task_type, ["help"]),
+            task_type=self._task_type,
+            step_number=self._state.step_count,
+            max_steps=self._max_steps,
+            done=done,
+            reward=reward,
+        )
+
+    def _status_footer(self) -> str:
+        step_info = f"Step: {self._state.step_count}/{self._max_steps}"
+        if self._task_type == "diagnosis":
+            ddx = ", ".join(self._ddx_list) if self._ddx_list else "empty"
+            accessed = ", ".join(sorted(self._accessed_sections)) if self._accessed_sections else "none"
+            return f"[STATUS] DDX: [{ddx}] | Accessed: {accessed} | {step_info}"
+        if self._task_type == "calculation":
+            return f"[STATUS] Case read: {'yes' if self._case_read else 'no'} | Calculator: {self._calculator_used or 'none'} | {step_info}"
+        if self._task_type == "note_review":
+            corr = str(dict(self._corrections)) if self._corrections else "none"
+            return f"[STATUS] Note read: {'yes' if self._note_read else 'no'} | Corrections: {corr} | {step_info}"
+        return f"[STATUS] {step_info}"
+
+    # ------------------------------------------------------------------
+    # Formatting
+    # ------------------------------------------------------------------
+
+    def _format_history(self, history: dict) -> str:
+        if not history or not any(history.values()):
+            return "No history data available."
+        field_map = {"pmh": "PMH", "medications": "Medications", "allergies": "Allergies", "social": "Social", "family": "Family"}
+        lines = []
+        for key, label in field_map.items():
+            val = history.get(key)
+            if val:
+                lines.append(f"{label}: {', '.join(val) if isinstance(val, list) else val}")
+        return "\n".join(lines) if lines else "No history data available."
+
+    def _format_vitals(self, vitals: dict) -> str:
+        if not vitals or not any(v for v in vitals.values() if v):
+            return "No vital signs recorded."
+        label_map = {"bp": "BP", "hr": "HR", "temp": "Temp", "rr": "RR", "spo2": "SpO2"}
+        parts = [f"{label}: {vitals[key]}" for key, label in label_map.items() if vitals.get(key)]
+        return " | ".join(parts) if parts else "No vital signs recorded."
+
+    def _format_dict(self, data, title: str = "") -> str:
+        if isinstance(data, dict):
+            lines = ([f"{title}:"] if title else []) + [f"  {k}: {v}" for k, v in data.items()]
+            return "\n".join(lines)
+        return f"{title}: {data}" if title else str(data)
+
+    def _format_note_sentences(self, sentences_raw: str) -> str:
+        formatted = []
+        for line in sentences_raw.strip().split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split(None, 1)
+            if parts[0].isdigit():
+                formatted.append(f"[{parts[0]}] {parts[1] if len(parts) > 1 else ''}")
+            else:
+                formatted.append(line)
+        return "\n".join(formatted)
+
+    @staticmethod
+    def _fuzzy_key_match(query: str, data: dict) -> str | None:
+        q = query.lower().strip()
+        for key in data:
+            if key.lower() == q:
+                return key
+        for key in data:
+            if q in key.lower() or key.lower() in q:
+                return key
+        return None

server/command_parser.py

@@ -0,0 +1,31 @@
+"""Parse CLI command strings into (command_name, args) tuples."""
+
+
+def parse(raw: str) -> tuple[str, list[str]]:
+    """
+    Parse a raw command string.
+
+    'chart.labs CBC'           -> ('chart.labs', ['CBC'])
+    'ddx.confirm Dengue fever' -> ('ddx.confirm', ['Dengue fever'])
+    'note.correct 5 Fixed.'    -> ('note.correct', ['5', 'Fixed.'])
+    'submit 25.2'              -> ('submit', ['25.2'])
+    'chart.vitals'             -> ('chart.vitals', [])
+    ''                         -> ('', [])
+    """
+    stripped = raw.strip()
+    if not stripped:
+        return ("", [])
+
+    parts = stripped.split(None, 1)
+    cmd = parts[0].lower()
+    rest = parts[1] if len(parts) > 1 else ""
+
+    if cmd == "note.correct" and rest:
+        tokens = rest.split(None, 1)
+        sentence_id = tokens[0]
+        correction_text = tokens[1] if len(tokens) > 1 else ""
+        return (cmd, [sentence_id, correction_text])
+
+    if rest:
+        return (cmd, [rest])
+    return (cmd, [])

server/constants.py

@@ -0,0 +1,102 @@
+"""Loads medical reference data from data/reference/ and provides lookup functions."""
+
+import json
+from pathlib import Path
+
+_data_dir: Path | None = None
+_lab_ranges: dict | None = None
+_diagnostic_criteria: dict | None = None
+_drug_info: dict | None = None
+
+
+def _find_reference_dir() -> Path:
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parent / "data" / "reference",
+        here / "data" / "reference",
+    ]
+    for c in candidates:
+        if c.is_dir():
+            return c
+    raise FileNotFoundError(f"data/reference/ not found. Checked: {candidates}")
+
+
+def _load():
+    global _lab_ranges, _diagnostic_criteria, _drug_info, _data_dir
+    if _lab_ranges is not None:
+        return
+    _data_dir = _find_reference_dir()
+    with open(_data_dir / "lab_ranges.json", encoding="utf-8") as f:
+        _lab_ranges = json.load(f)
+    with open(_data_dir / "diagnostic_criteria.json", encoding="utf-8") as f:
+        _diagnostic_criteria = json.load(f)
+    with open(_data_dir / "drug_info.json", encoding="utf-8") as f:
+        _drug_info = json.load(f)
+
+
+def _fuzzy_get(data: dict, key: str) -> tuple[str, any] | None:
+    k = key.strip().lower()
+    if k in data:
+        return k, data[k]
+    for dk, dv in data.items():
+        if k in dk or dk in k:
+            return dk, dv
+    return None
+
+
+def lookup_range(test_name: str) -> str | None:
+    _load()
+    match = _fuzzy_get(_lab_ranges, test_name)
+    if match is None:
+        return None
+    key, entry = match
+    result = f"{key.upper()}: Normal range {entry['low']}-{entry['high']} {entry['unit']}".strip()
+    if entry.get("context"):
+        result += f"\n  {entry['context']}"
+    return result
+
+
+def lookup_criteria(condition: str) -> str | None:
+    _load()
+    match = _fuzzy_get(_diagnostic_criteria, condition)
+    if match is None:
+        return None
+    return match[1]
+
+
+def lookup_drug(drug_name: str) -> str | None:
+    _load()
+    match = _fuzzy_get(_drug_info, drug_name)
+    if match is None:
+        return None
+    return match[1]
+
+
+def interpret_value(test_name: str, value_str: str) -> str | None:
+    _load()
+    match = _fuzzy_get(_lab_ranges, test_name)
+    if match is None:
+        return None
+
+    try:
+        value = float(value_str)
+    except (ValueError, TypeError):
+        return f"Cannot parse '{value_str}' as a numeric value."
+
+    key, entry = match
+    low, high, unit = entry["low"], entry["high"], entry["unit"]
+
+    if value < low:
+        status = "LOW"
+        severity = "critically low" if value < low * 0.7 else "below normal"
+    elif value > high:
+        status = "HIGH"
+        severity = "critically elevated" if value > high * 1.5 else "above normal"
+    else:
+        status = "NORMAL"
+        severity = "within normal range"
+
+    result = f"{key.upper()} {value} {unit}: {status} — {severity} (normal {low}-{high})"
+    if entry.get("context") and status != "NORMAL":
+        result += f"\n  {entry['context']}"
+    return result

server/data_loader.py

@@ -0,0 +1,101 @@
+"""Lazy-loading data access for all three clinical datasets."""
+
+import csv
+import json
+import os
+from pathlib import Path
+
+
+def _find_data_dir() -> Path:
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parent / "data",
+        here / "data",
+        Path(os.getcwd()) / "data",
+    ]
+    for c in candidates:
+        if c.is_dir():
+            return c
+    raise FileNotFoundError(f"data/ directory not found. Checked: {candidates}")
+
+
+class DataLoader:
+    def __init__(self):
+        self._diagnosis_cases: list[dict] | None = None
+        self._calculation_cases: list[dict] | None = None
+        self._note_cases: list[dict] | None = None
+        self._loaded = False
+
+    def load_all(self) -> None:
+        if self._loaded:
+            return
+        data_dir = _find_data_dir()
+        self._load_diagnosis(data_dir / "MedCaseReasoning")
+        self._load_calculations(data_dir / "MedCalcBench")
+        self._load_notes(data_dir / "MEDEC")
+        self._loaded = True
+
+    def _load_diagnosis(self, path: Path) -> None:
+        jsonl_path = path / "extracted_cases.jsonl"
+        cases = []
+        with open(jsonl_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    cases.append(json.loads(line))
+        self._diagnosis_cases = cases
+
+    def _load_calculations(self, path: Path) -> None:
+        cases = []
+        for filename in ["train_data.csv", "test_data.csv"]:
+            filepath = path / filename
+            if not filepath.exists():
+                continue
+            with open(filepath, "r", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    answer = row.get("Ground Truth Answer", "")
+                    if not answer or answer == "None":
+                        continue
+                    try:
+                        float(answer)
+                    except (ValueError, TypeError):
+                        continue
+                    cases.append(row)
+        self._calculation_cases = cases
+
+    def _load_notes(self, path: Path) -> None:
+        cases = []
+        filenames = [
+            "MEDEC-Full-TrainingSet-with-ErrorType.csv",
+            "MEDEC-MS-ValidationSet-with-GroundTruth-and-ErrorType.csv",
+            "MEDEC-MS-TestSet-with-GroundTruth-and-ErrorType.csv",
+        ]
+        for filename in filenames:
+            filepath = path / filename
+            if not filepath.exists():
+                continue
+            with open(filepath, "r", encoding="utf-8") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    if not row.get("Text", "").strip() and not row.get("Sentences", "").strip():
+                        continue
+                    flag = row.get("Error Flag", "0") or "0"
+                    try:
+                        row["Error Flag"] = int(float(flag))
+                    except (ValueError, TypeError):
+                        row["Error Flag"] = 0
+                    cases.append(row)
+        self._note_cases = cases
+
+    def get_diagnosis_cases(self) -> list[dict]:
+        self.load_all()
+        return self._diagnosis_cases or []
+
+    def get_calculation_cases(self) -> list[dict]:
+        self.load_all()
+        return self._calculation_cases or []
+
+    def get_note_cases(self) -> list[dict]:
+        self.load_all()
+        return self._note_cases or []

server/graders.py

@@ -0,0 +1,239 @@
+"""Dense reward functions for diagnosis, calculation, and note review tasks.
+
+Reward budgets per task type:
+  diagnosis:    0.30 intermediate + 0.70 terminal = 1.0
+  calculation:  0.15 intermediate + 0.85 terminal = 1.0
+  note_review:  0.10 intermediate + 0.90 terminal = 1.0
+"""
+
+from rapidfuzz import fuzz
+
+
+# ---------------------------------------------------------------------------
+# Diagnosis grading
+# ---------------------------------------------------------------------------
+
+def diagnosis_step_reward(
+    command: str,
+    args: list[str],
+    accessed_sections: set[str],
+    relevant_sections: set[str],
+) -> float:
+    """Step reward for chart exploration commands. Budget: 0.30 total."""
+    n = len(relevant_sections)
+    if n == 0:
+        return 0.0
+
+    per_section = 0.30 / n
+    section_key = _chart_command_to_section_key(command, args)
+    if section_key is None:
+        return 0.0
+    if section_key in accessed_sections:
+        return 0.0
+    if section_key not in relevant_sections:
+        return 0.0
+
+    accessed_sections.add(section_key)
+    return round(per_section, 4)
+
+
+def _chart_command_to_section_key(command: str, args: list[str]) -> str | None:
+    if command == "chart.history":
+        return "history"
+    if command == "chart.vitals":
+        return "vitals"
+    if command == "chart.labs" and args:
+        return f"labs.{args[0].lower()}"
+    if command == "chart.imaging" and args:
+        return f"imaging.{args[0].lower()}"
+    if command == "chart.exam" and args:
+        return f"exam.{args[0].lower()}"
+    return None
+
+
+def diagnosis_terminal_reward(
+    confirmed: str,
+    ground_truth_diagnosis: str,
+    accessed_sections: set[str],
+    relevant_sections: set[str],
+    ddx_list: list[str],
+    steps_taken: int,
+) -> float:
+    """Terminal reward on ddx.confirm. Budget: 0.70 total."""
+    n = max(len(relevant_sections), 1)
+
+    # Diagnostic accuracy (0.40)
+    ratio = fuzz.token_sort_ratio(confirmed.lower(), ground_truth_diagnosis.lower())
+    if ratio >= 80:
+        accuracy_score = 1.0
+    elif ratio >= 60:
+        accuracy_score = 0.5
+    else:
+        accuracy_score = 0.0
+    accuracy = 0.40 * accuracy_score
+
+    # Workup completeness (0.10)
+    accessed_relevant = len(accessed_sections & relevant_sections)
+    completeness = 0.10 * (accessed_relevant / n)
+
+    # Efficiency (0.10) — baseline is N+2 steps
+    excess = max(0, steps_taken - n - 2)
+    efficiency = 0.10 * max(0.0, 1.0 - excess / 20.0)
+
+    # Reasoning quality (0.10) — DDX breadth + whether answer was in DDX
+    ddx_breadth = min(len(ddx_list), 3) / 3.0 * 0.5
+    confirmed_in_ddx = 0.5 if any(
+        fuzz.token_sort_ratio(confirmed.lower(), d.lower()) >= 70
+        for d in ddx_list
+    ) else 0.0
+    reasoning = 0.10 * (ddx_breadth + confirmed_in_ddx)
+
+    return round(accuracy + completeness + efficiency + reasoning, 4)
+
+
+# ---------------------------------------------------------------------------
+# Calculation grading
+# ---------------------------------------------------------------------------
+
+def calculation_step_reward(command: str, case_read: bool, calculator_declared: bool) -> float:
+    """Step reward for case reading and calculator declaration. Budget: 0.15."""
+    if command == "case.read" and not case_read:
+        return 0.10
+    if command == "calculate" and not calculator_declared:
+        return 0.05
+    return 0.0
+
+
+def calculation_terminal_reward(
+    submitted_value: float,
+    ground_truth: float,
+    lower_limit: float,
+    upper_limit: float,
+    calculator_used: str,
+    expected_calculator: str,
+    steps_taken: int,
+) -> float:
+    """Terminal reward on submit. Budget: 0.85."""
+    # Numeric accuracy (0.50)
+    if lower_limit <= submitted_value <= upper_limit:
+        numeric_score = 1.0
+    else:
+        band = upper_limit - lower_limit
+        extended_lower = lower_limit - band
+        extended_upper = upper_limit + band
+        if extended_lower <= submitted_value <= extended_upper:
+            numeric_score = 0.5
+        else:
+            numeric_score = 0.0
+    numeric = 0.50 * numeric_score
+
+    # Correct calculator (0.25)
+    calc_ratio = fuzz.token_sort_ratio(calculator_used.lower(), expected_calculator.lower())
+    calc_match = 0.25 * (1.0 if calc_ratio >= 75 else 0.0)
+
+    # Efficiency (0.10) — perfect if ≤3 steps, linear decay to 0 at 10
+    if steps_taken <= 3:
+        eff_score = 1.0
+    elif steps_taken >= 10:
+        eff_score = 0.0
+    else:
+        eff_score = 1.0 - (steps_taken - 3) / 7.0
+    efficiency = 0.10 * eff_score
+
+    return round(numeric + calc_match + efficiency, 4)
+
+
+# ---------------------------------------------------------------------------
+# Note review grading
+# ---------------------------------------------------------------------------
+
+def note_step_reward(command: str, note_read: bool) -> float:
+    """Step reward for reading the note. Budget: 0.10."""
+    if command == "note.read" and not note_read:
+        return 0.10
+    return 0.0
+
+
+def note_terminal_reward(
+    corrections: dict[str, str],
+    has_error: bool,
+    error_sentence_id: str | None,
+    corrected_sentence: str | None,
+) -> float:
+    """Terminal reward on note.approve. Budget: 0.90."""
+    if not has_error:
+        # No error in note — agent should approve without corrections
+        if len(corrections) == 0:
+            return 0.90
+        # False positive penalty
+        return round(0.90 * max(0.0, 1.0 - len(corrections) * 0.3), 4)
+
+    # Note has an error — evaluate detection + correction
+    found_correct_sentence = False
+    correction_quality = 0.0
+
+    if error_sentence_id is not None:
+        target_id = str(error_sentence_id).strip()
+        if target_id in corrections:
+            found_correct_sentence = True
+            if corrected_sentence:
+                ratio = fuzz.ratio(
+                    corrections[target_id].strip().lower(),
+                    corrected_sentence.strip().lower(),
+                )
+                correction_quality = ratio / 100.0
+
+    # Error detection (0.40)
+    detection = 0.40 * (1.0 if found_correct_sentence else 0.0)
+
+    # Correction accuracy (0.40)
+    correction = 0.40 * correction_quality
+
+    # False positive penalty (0.10)
+    total_corrections = len(corrections)
+    true_positives = 1 if found_correct_sentence else 0
+    false_positives = total_corrections - true_positives
+    fp_penalty = 1.0 - (false_positives / max(total_corrections, 1))
+    no_fp = 0.10 * max(0.0, fp_penalty)
+
+    return round(detection + correction + no_fp, 4)
+
+
+# ---------------------------------------------------------------------------
+# Utility: compute relevant sections from extracted case data
+# ---------------------------------------------------------------------------
+
+def compute_relevant_sections(extracted: dict) -> set[str]:
+    """Build the set of non-empty data sections for a diagnosis case."""
+    sections = set()
+
+    if _has_data(extracted.get("vitals")):
+        sections.add("vitals")
+    if _has_data(extracted.get("history")):
+        sections.add("history")
+
+    for panel_name, panel_data in (extracted.get("labs") or {}).items():
+        if _has_data(panel_data):
+            sections.add(f"labs.{panel_name.lower()}")
+
+    for modality, findings in (extracted.get("imaging") or {}).items():
+        if _has_data(findings):
+            sections.add(f"imaging.{modality.lower()}")
+
+    for system, findings in (extracted.get("physical_exam") or {}).items():
+        if _has_data(findings):
+            sections.add(f"exam.{system.lower()}")
+
+    return sections
+
+
+def _has_data(value) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return bool(value.strip())
+    if isinstance(value, dict):
+        return any(_has_data(v) for v in value.values())
+    if isinstance(value, list):
+        return len(value) > 0
+    return True

server/requirements.txt

@@ -0,0 +1,7 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+rapidfuzz>=3.0.0
+
+
+

server/task_configs.py

@@ -0,0 +1,120 @@
+"""Difficulty tier definitions and case selection logic."""
+
+from random import Random
+
+SIMPLE_CALCULATORS = {
+    "bmi", "body mass index",
+    "anion gap",
+    "mean arterial pressure", "map",
+    "ideal body weight", "ibw",
+    "body surface area", "bsa",
+    "corrected sodium",
+    "corrected calcium",
+    "free water deficit",
+}
+
+COMPLEX_CALCULATORS = {
+    "apache ii", "apache",
+    "wells", "wells criteria",
+    "cha2ds2-vasc", "cha2ds2",
+    "curb-65", "curb",
+    "gcs", "glasgow coma scale",
+    "meld", "meld score",
+    "child-pugh", "child pugh",
+    "sofa", "sofa score",
+    "ranson", "ranson criteria",
+}
+
+SUBTLE_ERROR_TYPES = {"pharmacotherapy", "causalorganism", "causal organism"}
+
+
+def select_case(task_type: str, difficulty: str, cases: list[dict], rng: Random) -> dict:
+    filtered = _filter_by_difficulty(task_type, difficulty, cases)
+    if not filtered:
+        filtered = cases
+    return rng.choice(filtered)
+
+
+DEFAULT_TASK_TYPE = {
+    "easy": "note_review",
+    "medium": "calculation",
+    "hard": "diagnosis",
+}
+
+
+def get_default_task_type(difficulty: str, rng: Random | None = None) -> str:
+    return DEFAULT_TASK_TYPE.get(difficulty, "diagnosis")
+
+
+def _filter_by_difficulty(task_type: str, difficulty: str, cases: list[dict]) -> list[dict]:
+    if task_type == "diagnosis":
+        return _filter_diagnosis(difficulty, cases)
+    elif task_type == "calculation":
+        return _filter_calculation(difficulty, cases)
+    elif task_type == "note_review":
+        return _filter_notes(difficulty, cases)
+    return cases
+
+
+def _filter_diagnosis(difficulty: str, cases: list[dict]) -> list[dict]:
+    def score(c: dict) -> int:
+        try:
+            return int(c.get("score", 0))
+        except (ValueError, TypeError):
+            return 0
+
+    if difficulty == "easy":
+        return [c for c in cases if 12 <= score(c) <= 17]
+    elif difficulty == "medium":
+        return [c for c in cases if 17 < score(c) <= 22]
+    elif difficulty == "hard":
+        return [c for c in cases if score(c) > 22]
+    return cases
+
+
+def _matches_set(name: str, keyword_set: set[str]) -> bool:
+    return any(kw in name for kw in keyword_set)
+
+
+def _filter_calculation(difficulty: str, cases: list[dict]) -> list[dict]:
+    def calc_name(c: dict) -> str:
+        return (c.get("Calculator Name") or "").lower()
+
+    if difficulty == "easy":
+        return [c for c in cases if _matches_set(calc_name(c), SIMPLE_CALCULATORS)]
+    elif difficulty == "hard":
+        return [c for c in cases if _matches_set(calc_name(c), COMPLEX_CALCULATORS)]
+    elif difficulty == "medium":
+        return [
+            c for c in cases
+            if not _matches_set(calc_name(c), SIMPLE_CALCULATORS)
+            and not _matches_set(calc_name(c), COMPLEX_CALCULATORS)
+        ]
+    return cases
+
+
+def _filter_notes(difficulty: str, cases: list[dict]) -> list[dict]:
+    def error_flag(c: dict) -> int:
+        try:
+            return int(float(c.get("Error Flag", 0)))
+        except (ValueError, TypeError):
+            return 0
+
+    def error_type(c: dict) -> str:
+        return (c.get("Error Type") or "").lower().strip()
+
+    if difficulty == "easy":
+        return [c for c in cases if error_flag(c) == 0]
+    elif difficulty == "medium":
+        return [
+            c for c in cases
+            if error_flag(c) == 1
+            and error_type(c) not in SUBTLE_ERROR_TYPES
+        ]
+    elif difficulty == "hard":
+        return [
+            c for c in cases
+            if error_flag(c) == 1
+            and error_type(c) in SUBTLE_ERROR_TYPES
+        ]
+    return cases

server/ui.py

@@ -0,0 +1,418 @@
+"""Custom Gradio dashboard — plugs into OpenEnv's ``gradio_builder`` hook at /web."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+import gradio as gr
+
+_CSS = """
+    @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap');
+
+    .term-bar {
+        background: #1a2133;
+        border: 1px solid rgba(255,255,255,0.12);
+        border-bottom: none;
+        border-radius: 12px 12px 0 0;
+        padding: 11px 16px;
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        margin-top: 6px;
+        position: relative;
+        z-index: 2;
+        box-shadow: 0 -4px 20px rgba(0,0,0,0.3);
+    }
+    .term-dots { display: flex; gap: 7px; }
+    .term-dot { width: 11px; height: 11px; border-radius: 50%; }
+    .term-dot.r { background: #ff5f57; }
+    .term-dot.y { background: #febc2e; }
+    .term-dot.g { background: #28c840; }
+    .term-title {
+        font-family: 'JetBrains Mono', ui-monospace, monospace;
+        font-size: 11px;
+        color: #4a5568;
+        letter-spacing: 0.02em;
+    }
+
+    .terminal-area {
+        margin-top: 0 !important;
+        border: 1px solid rgba(255,255,255,0.12) !important;
+        border-top: 1px solid rgba(255,255,255,0.05) !important;
+        border-radius: 0 0 12px 12px !important;
+        overflow: hidden;
+        position: relative;
+        z-index: 1;
+        box-shadow:
+            0 8px 32px rgba(0,0,0,0.5),
+            0 2px 8px rgba(0,0,0,0.3),
+            inset 0 1px 0 rgba(255,255,255,0.03);
+        max-height: 720px !important;
+    }
+    .terminal-area .cm-scroller,
+    .terminal-area .code-block,
+    .terminal-area pre { max-height: 680px !important; overflow-y: auto !important; }
+    .terminal-area label { display: none !important; }
+    .terminal-area pre, .terminal-area code, .terminal-area textarea {
+        font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code',
+                    ui-monospace, monospace !important;
+        font-size: 13px !important;
+        line-height: 1.7 !important;
+        background: #0a0f18 !important;
+        color: #c9d1d9 !important;
+        letter-spacing: 0.01em !important;
+    }
+
+    .cmd-input input, .cmd-input textarea {
+        font-family: 'JetBrains Mono', ui-monospace, monospace !important;
+        font-size: 13px !important;
+        background: #151c28 !important;
+        color: #e2e8f0 !important;
+        border: 1px solid rgba(255,255,255,0.15) !important;
+        border-radius: 8px !important;
+        padding: 11px 14px !important;
+    }
+    .cmd-input input::placeholder, .cmd-input textarea::placeholder {
+        color: #64748b !important;
+    }
+
+    .sidebar-panel > div { padding: 0 !important; }
+    .execute-btn { min-width: 110px !important; }
+"""
+
+
+def _header_html() -> str:
+    return (
+        '<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:'
+        'wght@400;500;600;700&display=swap" rel="stylesheet">'
+        '<div style="padding:12px 0 4px;display:flex;align-items:baseline;gap:10px;">'
+        '<span style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:18px;'
+        'font-weight:700;color:#e2e8f0;letter-spacing:-0.03em;">'
+        '\U0001f3e5 Clinical Terminal</span>'
+        '<span style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:10px;'
+        'color:#3d4a5c;letter-spacing:0.08em;padding:2px 8px;'
+        'border:1px solid rgba(255,255,255,0.06);border-radius:4px;">v1.0</span>'
+        '</div>'
+    )
+
+
+def _terminal_bar_html() -> str:
+    return (
+        '<div class="term-bar">'
+        '<div class="term-dots">'
+        '<span class="term-dot r"></span>'
+        '<span class="term-dot y"></span>'
+        '<span class="term-dot g"></span>'
+        '</div>'
+        '<span class="term-title">claude code for healthcare</span>'
+        '</div>'
+    )
+
+
+def _score_html(score: float) -> str:
+    if score > 0:
+        color, glow, bg = "#4ade80", "rgba(74,222,128,0.3)", "#0c1f14"
+    elif score < 0:
+        color, glow, bg = "#f87171", "rgba(248,113,113,0.3)", "#1f0c0c"
+    else:
+        color, glow, bg = "#94a3b8", "rgba(148,163,184,0.1)", "#151c28"
+
+    return (
+        f'<div style="background:{bg};border:1px solid rgba(255,255,255,0.1);'
+        'border-radius:10px;padding:20px;text-align:center;margin-bottom:10px;">'
+        '<div style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:10px;'
+        'color:#8b949e;text-transform:uppercase;letter-spacing:2px;'
+        'margin-bottom:8px;">Episode Score</div>'
+        f'<div style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:38px;'
+        f'font-weight:700;color:{color};font-variant-numeric:tabular-nums;'
+        f'text-shadow:0 0 30px {glow},0 0 60px {glow};'
+        f'letter-spacing:-0.02em;">{score:.2f}</div></div>'
+    )
+
+
+def _status_html(
+    task_type: str,
+    difficulty: str,
+    step: int,
+    max_steps: int,
+) -> str:
+    pct = int(step / max_steps * 100) if max_steps else 0
+    bar_color = "#3b82f6" if pct < 75 else "#f59e0b" if pct < 95 else "#ef4444"
+
+    badge_bg, badge_fg = "rgba(96,165,250,0.15)", "#7db8f7"
+    if task_type == "diagnosis":
+        badge_bg, badge_fg = "rgba(251,191,36,0.15)", "#fcd34d"
+    elif task_type == "calculation":
+        badge_bg, badge_fg = "rgba(167,139,250,0.15)", "#c4b5fd"
+    elif task_type == "note_review":
+        badge_bg, badge_fg = "rgba(52,211,153,0.15)", "#6ee7b7"
+
+    lbl = ("font-size:10px;color:#6b7d94;text-transform:uppercase;"
+           "letter-spacing:1px;font-family:'JetBrains Mono',monospace;")
+
+    return (
+        '<div style="background:#151c28;border:1px solid rgba(255,255,255,0.1);'
+        'border-radius:10px;padding:16px;margin-bottom:10px;">'
+        f'<div style="{lbl}margin-bottom:14px;font-weight:600;">Status</div>'
+        f'<div style="margin-bottom:14px;"><span style="{lbl}">Task</span><br/>'
+        f'<span style="display:inline-block;background:{badge_bg};'
+        f'color:{badge_fg};padding:3px 10px;border-radius:5px;'
+        'font-family:&#39;JetBrains Mono&#39;,monospace;font-size:12px;'
+        f'font-weight:600;margin-top:4px;">{task_type or chr(0x2014)}</span></div>'
+        f'<div style="margin-bottom:14px;"><span style="{lbl}">Difficulty</span><br/>'
+        '<span style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:13px;'
+        f'color:#c9d1d9;margin-top:2px;display:inline-block;">'
+        f'{difficulty or chr(0x2014)}</span></div>'
+        f'<div><span style="{lbl}">Progress</span>'
+        '<div style="display:flex;align-items:center;gap:8px;margin-top:6px;">'
+        '<div style="flex:1;height:4px;background:rgba(255,255,255,0.08);'
+        'border-radius:2px;overflow:hidden;">'
+        f'<div style="width:{pct}%;height:100%;background:{bar_color};'
+        'border-radius:2px;transition:width .4s ease;"></div></div>'
+        '<span style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:11px;'
+        f'color:#8b949e;font-weight:600;">{step}/{max_steps}</span>'
+        '</div></div></div>'
+    )
+
+
+def _commands_html(cmds: List[str]) -> str:
+    lbl = ("font-family:'JetBrains Mono',monospace;font-size:10px;color:#6b7d94;"
+           "text-transform:uppercase;letter-spacing:1px;font-weight:600;")
+    if not cmds:
+        return (
+            '<div style="background:#151c28;border:1px solid rgba(255,255,255,0.1);'
+            'border-radius:10px;padding:16px;">'
+            f'<div style="{lbl}margin-bottom:8px;">Commands</div>'
+            '<p style="font-family:&#39;JetBrains Mono&#39;,monospace;font-size:11px;'
+            'color:#6b7d94;margin:0;font-style:italic;">awaiting reset\u2026</p></div>'
+        )
+
+    items = "".join(
+        f'<div style="padding:4px 0;font-family:&#39;JetBrains Mono&#39;,monospace;'
+        f'font-size:12px;color:#c9d1d9;border-bottom:1px solid rgba(255,255,255,0.05);">'
+        f'<span style="color:#58a6ff;margin-right:6px;">\u203a</span>{c}</div>'
+        for c in cmds
+    )
+    return (
+        '<div style="background:#151c28;border:1px solid rgba(255,255,255,0.1);'
+        'border-radius:10px;padding:16px;">'
+        f'<div style="{lbl}margin-bottom:10px;">Commands</div>'
+        f'{items}</div>'
+    )
+
+    items = "".join(
+        f'<div style="padding:3px 0;font-family:&#39;JetBrains Mono&#39;,monospace;'
+        f'font-size:11px;color:#8b949e;border-bottom:1px solid rgba(255,255,255,0.03);">'
+        f'<span style="color:#3d4a5c;margin-right:4px;">\u203a</span> {c}</div>'
+        for c in cmds
+    )
+    return (
+        '<div style="background:#0d1117;border:1px solid rgba(255,255,255,0.06);'
+        'border-radius:10px;padding:16px;">'
+        f'<div style="{lbl}font-size:10px;color:#4a5568;margin-bottom:10px;">Commands</div>'
+        f'{items}</div>'
+    )
+
+
+_TASK_OPTIONS = [
+    "Easy \u2014 Note Review",
+    "Medium \u2014 Calculation",
+    "Hard \u2014 Diagnosis",
+]
+_TASK_KEY = {
+    _TASK_OPTIONS[0]: "easy",
+    _TASK_OPTIONS[1]: "medium",
+    _TASK_OPTIONS[2]: "hard",
+}
+
+
+def build_custom_dashboard(
+    web_manager: Any,
+    action_fields: List[Dict[str, Any]],
+    metadata: Any,
+    is_chat_env: bool,
+    title: str,
+    quick_start_md: Optional[str],
+) -> gr.Blocks:
+    """Return a ``gr.Blocks`` app for the Custom tab at /web."""
+
+    async def on_reset(difficulty: str):
+        task_key = _TASK_KEY.get(difficulty, "easy")
+        try:
+            data = await web_manager.reset_environment(
+                {"options": {"task": task_key}}
+            )
+        except Exception as exc:
+            return (
+                f"ERROR: {exc}",
+                _status_html("\u2014", "\u2014", 0, 50),
+                _commands_html([]),
+                _score_html(0.0),
+                "",
+            )
+
+        obs = data.get("observation", {})
+        output = obs.get("output", "")
+        task_type = obs.get("task_type", "")
+        step = obs.get("step_number", 0)
+        max_steps = obs.get("max_steps", 50)
+        cmds = obs.get("available_commands", [])
+
+        pipe = "\u2502"
+        indented_output = output.replace(chr(10), chr(10) + " " + pipe + "  ")
+        terminal = (
+            f" \u250c\u2500 {task_type.upper()} \u2500\u2500 new episode\n"
+            f" {pipe}\n"
+            f" {pipe}  {indented_output}\n"
+            f" {pipe}\n"
+            f" \u2514\u2500\u2500\u2500\n"
+        )
+
+        return (
+            terminal,
+            _status_html(task_type, task_key, step, max_steps),
+            _commands_html(cmds),
+            _score_html(0.0),
+            "",
+        )
+
+    async def on_step(command: str, history: str):
+        if not command or not command.strip():
+            return (
+                history or "",
+                "",
+                gr.update(),
+                gr.update(),
+                gr.update(),
+            )
+
+        try:
+            data = await web_manager.step_environment(
+                {"command": command.strip()}
+            )
+        except Exception as exc:
+            return (
+                (history or "") + f"\n\u276f {command}\n  \u2718 {exc}\n",
+                "",
+                gr.update(),
+                gr.update(),
+                gr.update(),
+            )
+
+        obs = data.get("observation", {})
+        output = obs.get("output", "")
+        error = obs.get("error", "")
+        reward = data.get("reward", 0.0)
+        done = data.get("done", False)
+        step = obs.get("step_number", 0)
+        max_steps = obs.get("max_steps", 50)
+        task_type = obs.get("task_type", "")
+        cmds = obs.get("available_commands", [])
+
+        entry = f"\n\u276f {command}\n"
+        if error:
+            entry += f"  \u2718 {error}\n"
+        entry += f"  {output.replace(chr(10), chr(10) + '  ')}\n"
+        if reward != 0:
+            sign = "+" if reward > 0 else ""
+            entry += f"  \u2500\u2500 reward: {sign}{reward:.4f}\n"
+        if done:
+            entry += "\n  \u2588\u2588 EPISODE COMPLETE \u2588\u2588\n"
+
+        full = (history or "") + entry
+
+        try:
+            state = web_manager.get_state()
+            score = state.get("total_score", 0.0)
+            difficulty = state.get("difficulty", "")
+        except Exception:
+            score = 0.0
+            difficulty = ""
+
+        return (
+            full,
+            "",
+            _status_html(task_type, difficulty, step, max_steps),
+            _commands_html(cmds),
+            _score_html(score),
+        )
+
+    _SCROLL_JS = """
+    () => {
+        setTimeout(() => {
+            const s = document.querySelector('.terminal-area .cm-scroller')
+                   || document.querySelector('.terminal-area pre');
+            if (s) s.scrollTop = s.scrollHeight;
+        }, 150);
+    }
+    """
+
+    with gr.Blocks() as blocks:
+        gr.HTML(f"<style>{_CSS}</style>" + _header_html())
+
+        with gr.Row(equal_height=False):
+            with gr.Column(scale=7, min_width=480):
+                with gr.Row():
+                    difficulty = gr.Dropdown(
+                        choices=_TASK_OPTIONS,
+                        value=_TASK_OPTIONS[0],
+                        label="Task",
+                        scale=3,
+                        interactive=True,
+                    )
+                    reset_btn = gr.Button(
+                        "Start Episode",
+                        variant="primary",
+                        scale=1,
+                    )
+
+                gr.HTML(_terminal_bar_html())
+
+                terminal = gr.Code(
+                    value=(
+                        "  Welcome to Claude Code for Healthcare.\n"
+                        "  Select a task and press Start Episode.\n"
+                        + "\n" * 18
+                    ),
+                    label="Terminal",
+                    language=None,
+                    lines=20,
+                    interactive=False,
+                    elem_classes=["terminal-area"],
+                )
+
+            with gr.Column(scale=3, min_width=250, elem_classes=["sidebar-panel"]):
+                score_md = gr.HTML(_score_html(0.0))
+                cmd_input = gr.Textbox(
+                    placeholder="\u276f type a command\u2026",
+                    label="Command",
+                    elem_classes=["cmd-input"],
+                )
+                send_btn = gr.Button(
+                    "Execute \u21b5",
+                    variant="primary",
+                    elem_classes=["execute-btn"],
+                )
+                status_md = gr.HTML(_status_html("\u2014", "\u2014", 0, 50))
+                commands_md = gr.HTML(_commands_html([]))
+
+        reset_outputs = [terminal, status_md, commands_md, score_md, cmd_input]
+        step_outputs = [terminal, cmd_input, status_md, commands_md, score_md]
+
+        reset_btn.click(
+            fn=on_reset,
+            inputs=[difficulty],
+            outputs=reset_outputs,
+        ).then(fn=None, js=_SCROLL_JS)
+        send_btn.click(
+            fn=on_step,
+            inputs=[cmd_input, terminal],
+            outputs=step_outputs,
+        ).then(fn=None, js=_SCROLL_JS)
+        cmd_input.submit(
+            fn=on_step,
+            inputs=[cmd_input, terminal],
+            outputs=step_outputs,
+        ).then(fn=None, js=_SCROLL_JS)
+
+    return blocks

validate-submission.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+#
+# validate-submission.sh — OpenEnv Submission Validator
+#
+# Checks that your HF Space is live, Docker image builds, and openenv validate passes.
+#
+# Prerequisites:
+#   - Docker:       https://docs.docker.com/get-docker/
+#   - openenv-core: pip install openenv-core
+#   - curl (usually pre-installed)
+#
+# Run:
+#   curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/main/scripts/validate-submission.sh | bash -s -- <ping_url> [repo_dir]
+#
+#   Or download and run locally:
+#     chmod +x validate-submission.sh
+#     ./validate-submission.sh <ping_url> [repo_dir]
+#
+# Arguments:
+#   ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)
+#   repo_dir   Path to your repo (default: current directory)
+#
+# Examples:
+#   ./validate-submission.sh https://my-team.hf.space
+#   ./validate-submission.sh https://my-team.hf.space ./my-repo
+#
+
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BOLD='' NC=''
+fi
+
+run_with_timeout() {
+  local secs="$1"; shift
+  if command -v timeout &>/dev/null; then
+    timeout "$secs" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$secs" "$@"
+  else
+    "$@" &
+    local pid=$!
+    ( sleep "$secs" && kill "$pid" 2>/dev/null ) &
+    local watcher=$!
+    wait "$pid" 2>/dev/null
+    local rc=$?
+    kill "$watcher" 2>/dev/null
+    wait "$watcher" 2>/dev/null
+    return $rc
+  fi
+}
+
+portable_mktemp() {
+  local prefix="${1:-validate}"
+  mktemp "${TMPDIR:-/tmp}/${prefix}-XXXXXX" 2>/dev/null || mktemp
+}
+
+CLEANUP_FILES=()
+cleanup() { rm -f "${CLEANUP_FILES[@]+"${CLEANUP_FILES[@]}"}"; }
+trap cleanup EXIT
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  printf "\n"
+  printf "  ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)\n"
+  printf "  repo_dir   Path to your repo (default: current directory)\n"
+  exit 1
+fi
+
+if ! REPO_DIR="$(cd "$REPO_DIR" 2>/dev/null && pwd)"; then
+  printf "Error: directory '%s' not found\n" "${2:-.}"
+  exit 1
+fi
+PING_URL="${PING_URL%/}"
+export PING_URL
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS + 1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() {
+  printf "\n"
+  printf "${RED}${BOLD}Validation stopped at %s.${NC} Fix the above before continuing.\n" "$1"
+  exit 1
+}
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  OpenEnv Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+printf "\n"
+
+log "${BOLD}Step 1/3: Pinging HF Space${NC} ($PING_URL/reset) ..."
+
+CURL_OUTPUT=$(portable_mktemp "validate-curl")
+CLEANUP_FILES+=("$CURL_OUTPUT")
+HTTP_CODE=$(curl -s -o "$CURL_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 2>"$CURL_OUTPUT" || printf "000")
+
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live and responds to /reset"
+elif [ "$HTTP_CODE" = "000" ]; then
+  fail "HF Space not reachable (connection failed or timed out)"
+  hint "Check your network connection and that the Space is running."
+  hint "Try: curl -s -o /dev/null -w '%%{http_code}' -X POST $PING_URL/reset"
+  stop_at "Step 1"
+else
+  fail "HF Space /reset returned HTTP $HTTP_CODE (expected 200)"
+  hint "Make sure your Space is running and the URL is correct."
+  hint "Try opening $PING_URL in your browser first."
+  stop_at "Step 1"
+fi
+
+log "${BOLD}Step 2/3: Running docker build${NC} ..."
+
+if ! command -v docker &>/dev/null; then
+  fail "docker command not found"
+  hint "Install Docker: https://docs.docker.com/get-docker/"
+  stop_at "Step 2"
+fi
+
+if [ -f "$REPO_DIR/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR"
+elif [ -f "$REPO_DIR/server/Dockerfile" ]; then
+  DOCKER_CONTEXT="$REPO_DIR/server"
+else
+  fail "No Dockerfile found in repo root or server/ directory"
+  stop_at "Step 2"
+fi
+
+log "  Found Dockerfile in $DOCKER_CONTEXT"
+
+BUILD_OK=false
+BUILD_OUTPUT=$(run_with_timeout "$DOCKER_BUILD_TIMEOUT" docker build "$DOCKER_CONTEXT" 2>&1) && BUILD_OK=true
+
+if [ "$BUILD_OK" = true ]; then
+  pass "Docker build succeeded"
+else
+  fail "Docker build failed (timeout=${DOCKER_BUILD_TIMEOUT}s)"
+  printf "%s\n" "$BUILD_OUTPUT" | tail -20
+  stop_at "Step 2"
+fi
+
+log "${BOLD}Step 3/3: Running openenv validate${NC} ..."
+
+if ! command -v openenv &>/dev/null; then
+  fail "openenv command not found"
+  hint "Install it: pip install openenv-core"
+  stop_at "Step 3"
+fi
+
+VALIDATE_OK=false
+VALIDATE_OUTPUT=$(cd "$REPO_DIR" && openenv validate 2>&1) && VALIDATE_OK=true
+
+if [ "$VALIDATE_OK" = true ]; then
+  pass "openenv validate passed"
+  [ -n "$VALIDATE_OUTPUT" ] && log "  $VALIDATE_OUTPUT"
+else
+  fail "openenv validate failed"
+  printf "%s\n" "$VALIDATE_OUTPUT"
+  stop_at "Step 3"
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${GREEN}${BOLD}  All 3/3 checks passed!${NC}\n"
+printf "${GREEN}${BOLD}  Your submission is ready to submit.${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+printf "\n"
+
+exit 0