this is the first commit to creating the project

.gitattributes

@@ -1,2 +1,22 @@
-# Auto detect text files and perform LF normalization
+# Auto-detect text files and normalize line endings
 * text=auto
+
+# Enforce LF line endings for source code and config files
+*.py text eol=lf
+*.sh text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.txt text eol=lf
+*.ipynb text eol=lf
+
+# Binary assets (do not modify)
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.pdf binary
+
+# Custom diff driver for Python files
+*.py diff=python

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+# Prevent .pyc files and enable unbuffered stdout for structured logging
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+# Install dependencies first (layer caching)
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy project source
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "server.app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,2 +1,200 @@
-# meta-huggingface-hackathon-team-silver-orca
+# Clinical Note Scribe
 
+An **OpenEnv-compliant** environment for evaluating AI agents on clinical SOAP-note generation from doctor–patient transcripts.
+
+Built for the **Meta × Hugging Face OpenEnv Hackathon**.
+
+---
+
+## Environment Description
+
+A doctor–patient conversation is recorded as a text transcript. The agent's goal is to read the transcript along with structured patient context (demographics, medications, labs) and produce a clinically accurate, concise **SOAP note** (Subjective, Objective, Assessment, Plan).
+
+The agent interacts through a standard `reset()` / `step()` / `state()` API. Three action types are available: submit a full note, request clarification, or revise a single section. A multi-signal reward function scores each submission on clinical accuracy, conciseness, safe language, and structural validity, with penalties for excessive steps or invalid actions.
+
+---
+
+## Observation Space
+
+| Field | Type | Description |
+|---|---|---|
+| `transcript` | `str` | Full doctor–patient transcript for the current task |
+| `task_id` | `str` | Unique identifier for the active task |
+| `patient_context` | `dict[str, Any]` | Structured patient demographics, conditions, medications, allergies, and labs |
+| `current_draft` | `Optional[str]` | The agent's most recent SOAP-note draft (null until first submission or revision) |
+| `errors_so_far` | `list[str]` | Accumulated error/feedback messages from prior invalid actions |
+| `step_count` | `int` | Number of steps taken so far in the current episode (0-indexed at reset) |
+
+---
+
+## Action Space
+
+| Field | Type | Description |
+|---|---|---|
+| `action_type` | `Literal["submit_note", "request_clarify", "revise_section"]` | **Required.** The kind of action the agent is taking |
+| `soap_note` | `Optional[SOAPNote]` | Complete SOAP note — **required** when `action_type == "submit_note"` |
+| `section` | `Optional[Literal["S", "O", "A", "P"]]` | Which SOAP section to revise — **required** when `action_type == "revise_section"` |
+| `revision_text` | `Optional[str]` | Replacement text for the section — **required** when `action_type == "revise_section"` |
+| `clarify_question` | `Optional[str]` | Free-text question — **required** when `action_type == "request_clarify"` |
+
+### SOAPNote Schema
+
+| Field | Type | Description |
+|---|---|---|
+| `subjective` | `str` | Patient's self-reported symptoms, history, and concerns |
+| `objective` | `str` | Clinician's measurable findings — vitals, exam, labs, imaging |
+| `assessment` | `str` | Differential diagnoses and clinical reasoning |
+| `plan` | `str` | Treatment plan, medications, follow-ups, referrals |
+
+---
+
+## Tasks
+
+### 🟢 Easy — Routine Check-Up
+**Task ID:** `easy_routine_checkup` · **Max steps:** 5
+
+A 6-turn dialogue about a common cold and blood pressure screening for a 34-year-old female. Straightforward clinical picture with no complications.
+
+### 🟡 Medium — Chronic Disease Follow-Up
+**Task ID:** `medium_chronic_disease_followup` · **Max steps:** 8
+
+A 14-turn follow-up visit for a 58-year-old male with Type 2 Diabetes and Hypertension. Includes HbA1c lab review (7.2% → 7.8%), medication adjustments (adding glipizide 5 mg, uptitrating lisinopril 20 → 40 mg), a 2-week statin gap, and dietary counselling around restaurant meals.
+
+### 🔴 Hard — Complex ER Visit
+**Task ID:** `hard_complex_er_visit` · **Max steps:** 10
+
+A rapid 20-turn emergency-room encounter for a 72-year-old female with CAD, AFib, and CKD Stage 3. Overlapping chest pain and shortness of breath with a dual ACS vs PE differential. Includes a patient self-contradiction (denied then admitted nitroglycerin use at home), contrast dye allergy complicating CT-PA workup (V/Q scan ordered instead), elevated D-dimer (1840 ng/mL), and Cardiac ICU admission.
+
+---
+
+## Reward Function
+
+```
+value = clamp(weighted_sum − deductions, 0.0, 1.0)
+```
+
+| Signal | Weight | Criteria |
+|---|---|---|
+| `grader_score` | × 0.60 | Clinical accuracy from task-specific grader |
+| `conciseness_bonus` | × 0.10 | 1.0 if total SOAP note ≤ 400 words |
+| `safe_language_score` | × 0.15 | 1.0 if no unsafe-certainty phrases detected |
+| `format_valid` | × 0.15 | 1.0 if all four SOAP fields are non-empty |
+
+| Deduction | Rate | Trigger |
+|---|---|---|
+| Step penalty | −0.05 | Per step beyond 3 (penalises excessive clarification) |
+| Error penalty | −0.10 | Per invalid action in `errors_so_far` |
+
+---
+
+## Setup Instructions
+
+### Prerequisites
+
+- Python 3.11+
+- An OpenAI-compatible API key (set as `OPENAI_API_KEY`)
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/<your-org>/meta-huggingface-hackathon-team-silver-orca.git
+cd meta-huggingface-hackathon-team-silver-orca
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Start the environment server
+uvicorn server.app:app --host 0.0.0.0 --port 7860
+
+# In another terminal — run the baseline inference
+export OPENAI_API_KEY="sk-..."
+export MODEL_NAME="gpt-4o-mini"           # or any OpenAI-compatible model
+export API_BASE_URL="https://api.openai.com/v1"
+python inference.py
+```
+
+### Docker
+
+```bash
+docker build -t meta-huggingface-hackathon-team-silver-orca .
+docker run -p 7860:7860 meta-huggingface-hackathon-team-silver-orca
+```
+
+### API Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Liveness probe → `{"status": "ok"}` |
+| `POST` | `/reset` | Start a new episode → `Observation` |
+| `POST` | `/step` | Submit an action → `{observation, reward, done, info}` |
+| `GET` | `/state` | Inspect environment state → `EnvironmentState` |
+
+---
+
+## Baseline Scores
+
+Scores obtained using `gpt-4o-mini` with `temperature=0.2` via `inference.py`:
+
+| Task | Difficulty | Score |
+|---|---|---|
+| `easy_routine_checkup` | 🟢 Easy | 0.7000 |
+| `medium_chronic_disease_followup` | 🟡 Medium | 0.7000 |
+| `hard_complex_er_visit` | 🔴 Hard | 0.7000 |
+| **Average** | | **0.7000** |
+
+> **Note:** These baseline scores use placeholder graders (returning 0.5). Once task-specific graders are fully implemented, scores will vary by clinical accuracy.
+
+---
+
+## Structured Logging
+
+Every episode emits JSON log lines to stdout, scraped by the OpenEnv validator:
+
+```json
+{"event": "START", "task_id": "easy_routine_checkup", "timestamp": 1700000000.0}
+{"event": "STEP",  "step": 1, "action_type": "submit_note", "reward": 0.82}
+{"event": "END",   "task_id": "easy_routine_checkup", "final_score": 0.82}
+```
+
+---
+
+## Project Structure
+
+```
+meta-huggingface-hackathon-team-silver-orca/
+├── openenv.yaml              ← OpenEnv spec metadata + graders
+├── inference.py              ← Baseline inference (OpenAI client, all 3 tasks)
+├── Dockerfile                ← Containerised server (port 7860)
+├── README.md                 ← This file
+├── requirements.txt
+│
+├── environment/
+│   ├── __init__.py
+│   ├── models.py             ← Pydantic v2 models (Observation, Action, Reward, …)
+│   ├── env.py                ← ClinicalNoteScribeEnv (reset/step/state)
+│   ├── reward.py             ← Multi-signal reward function
+│   └── tasks/
+│       ├── __init__.py       ← Task & grader registries
+│       ├── task_easy.py      ← Routine check-up + grader stub
+│       ├── task_medium.py    ← Chronic disease follow-up + grader stub
+│       └── task_hard.py      ← Complex ER visit + grader stub
+│
+├── server/
+│   ├── __init__.py
+│   ├── app.py                ← FastAPI application
+│   └── routes.py             ← API route definitions
+│
+└── data/
+    ├── transcripts/
+    │   ├── easy.txt           ← 6-turn routine check-up transcript
+    │   ├── medium.txt         ← 14-turn chronic disease follow-up transcript
+    │   └── hard.txt           ← 20-turn complex ER visit transcript
+    └── clarify_answers.json   ← Clarification Q&A lookup (10 entries)
+```
+
+---
+
+## License
+
+MIT

data/clarify_answers.json

@@ -0,0 +1,14 @@
+{
+    "did the patient report any fever?": "No. Jane Doe denied fever throughout the visit. She mentioned mild body aches in the first two days that had since resolved.",
+    "what over-the-counter medications has the patient tried?": "The patient took generic DayQuil for two days but stopped because she was uncertain about interactions with her penicillin allergy. No other OTC medications were tried.",
+    "what was the patient's blood pressure reading?": "Blood pressure was 118/76 mmHg with a heart rate of 72 bpm, recorded during the visit.",
+
+    "what is the patient's current hba1c and how does it compare to the previous?": "HbA1c is 7.8%, up from 7.2% three months ago, indicating worsening glycemic control over the past quarter.",
+    "what dietary changes were discussed with the patient?": "The patient reported eating out at a barbecue restaurant 1-2 times per week with high-carb sides. The physician recommended limiting restaurant meals to once weekly and substituting starchy sides with salads or steamed vegetables.",
+    "was a new medication added for diabetes and what are the side effects?": "Glipizide 5 mg once daily with breakfast was added. The main side effect discussed was potential hypoglycemia (shakiness, sweating, lightheadedness) and modest weight gain.",
+    "why was lisinopril increased?": "Home blood pressure readings were averaging 135/85 and the in-office reading was 142/88, both above the target of 130/80 for a diabetic patient. The dose was increased from 20 mg to 40 mg daily. The patient reported no cough or dizziness on the current dose.",
+
+    "did the patient mention any recent travel or immobilization?": "Yes. The patient initially denied travel but then corrected herself — her daughter drove her to Sacramento last weekend, approximately five hours each way, during which she was mostly sitting.",
+    "why was ct-pa not ordered for the pe workup?": "The patient has a documented contrast dye allergy and chronic kidney disease with eGFR of 34 mL/min. Both are relative contraindications to IV contrast, so a V/Q scan was ordered instead.",
+    "did the patient contradict herself during the encounter?": "Yes. The patient initially stated the chest pain started while watching TV and she came straight in. She later disclosed that she had taken a nitroglycerin tablet at home before calling 911, which provided transient partial relief for about five minutes before the pain returned."
+}

data/transcripts/easy.txt

@@ -0,0 +1,25 @@
+DR. PATEL: Good morning, Jane. What brings you in today?
+
+JANE DOE: Hi, Doctor. I've had this cold for about five days now — runny nose, scratchy throat, and I've been sneezing a lot. I thought it would go away on its own, but it's lingering.
+
+DR. PATEL: I see. Any fever, body aches, or chills along with it?
+
+JANE DOE: No fever that I've noticed. Maybe some mild body aches the first couple of days, but nothing now. Mostly it's the congestion that's really bothering me — I can barely breathe through my nose at night.
+
+DR. PATEL: That sounds uncomfortable. Have you tried any over-the-counter medications — decongestants, antihistamines, anything like that?
+
+JANE DOE: I took some generic DayQuil for two days but honestly I couldn't tell if it helped much. I stopped because I wasn't sure if it was okay with my penicillin allergy.
+
+DR. PATEL: That's good you're being cautious, but DayQuil doesn't contain penicillin so that's fine to use. Let me take a quick look at your throat and ears. — Okay, throat is mildly erythematous, no exudates. Tympanic membranes are clear bilaterally. Lungs are clear to auscultation. No lymphadenopathy. Let me also check your blood pressure since you're here — we like to keep an eye on that annually. — Blood pressure is 118 over 76, heart rate 72. That's excellent.
+
+JANE DOE: Oh good, I was a little worried about that because my mom was just diagnosed with high blood pressure.
+
+DR. PATEL: I understand the concern. Your numbers look great right now. Family history is something we'll keep monitoring, but at 34 with these readings, you're in a good spot. As for the cold — this looks like a straightforward upper respiratory infection, viral in nature. I'd recommend continuing the DayQuil during the day, switching to NyQuil at bedtime for the congestion, plenty of fluids, and rest. If it's not improving in another five to seven days, or if you develop a fever above 101, come back and we'll reassess.
+
+JANE DOE: Sounds good. Should I worry about it turning into a sinus infection?
+
+DR. PATEL: It's possible but unlikely at this stage. The things to watch for would be facial pressure or pain around your cheeks and forehead, thick yellow-green nasal discharge, or symptoms that seem to get better and then suddenly worsen. If any of that happens, give us a call. Otherwise, I think you'll be on the mend soon.
+
+JANE DOE: Great, thank you so much, Doctor.
+
+DR. PATEL: You're welcome, Jane. Feel better!

data/transcripts/hard.txt

@@ -0,0 +1,67 @@
+TRIAGE NURSE: 72-year-old female, Maria Garcia, presenting with acute onset chest pain and shortness of breath. Pain started approximately ninety minutes ago. She's on warfarin. Vitals on arrival: BP 168 over 94, heart rate 112 and irregular, respiratory rate 22, SpO2 91 percent on room air, temp 37.2. She's being moved to Bed 4 in the acute bay.
+
+DR. OKONKWO: Mrs. Garcia, I'm Dr. Okonkwo. I can see you're in some distress. Can you tell me about the pain you're feeling?
+
+MARIA GARCIA: It's — it's right here in the center of my chest. It feels like a heavy pressure, like someone's sitting on me. And I can't catch my breath. It started when I was watching television, I wasn't doing anything strenuous.
+
+DR. OKONKWO: On a scale of zero to ten, how severe is the pain right now?
+
+MARIA GARCIA: Maybe a seven. It was worse when it started, maybe an eight or nine.
+
+DR. OKONKWO: Does the pain go anywhere — into your arm, your jaw, your back?
+
+MARIA GARCIA: A little into my left arm. Not my jaw. Maybe a tiny bit in my back between my shoulder blades.
+
+DR. OKONKWO: Okay. Any nausea, vomiting, or dizziness?
+
+MARIA GARCIA: I felt nauseous in the ambulance, but I didn't throw up. A little lightheaded, yes.
+
+DR. OKONKWO: Have you had chest pain like this before?
+
+MARIA GARCIA: I had a similar episode about two years ago and they said it was angina. They gave me nitroglycerin and it went away. But this feels different — stronger, and the breathing is worse this time.
+
+DR. OKONKWO: I see from your chart you have coronary artery disease, atrial fibrillation, and chronic kidney disease stage 3. You're on warfarin, metoprolol, aspirin, furosemide, and amlodipine. Have you taken all your medications today?
+
+MARIA GARCIA: Yes, I took everything this morning like I always do.
+
+DR. OKONKWO: Any recent travel — long car rides, flights?
+
+MARIA GARCIA: No, no travel. I've been — actually, wait. My daughter drove me to Sacramento last weekend. It was about a five-hour drive each way and I was mostly sitting in the car.
+
+DR. OKONKWO: That's important. Any leg swelling, redness, or calf pain since that trip?
+
+MARIA GARCIA: Now that you mention it, my left calf has been a little sore. I thought it was just from sitting so long. It's not swollen though — I don't think. Maybe a little.
+
+DR. OKONKWO: Let me examine you. — Chest auscultation: irregular rhythm, no murmurs or gallops appreciated. Diminished breath sounds at the right base with fine crackles. Abdomen soft, non-tender. Left calf is mildly tender to palpation with trace edema compared to the right. No erythema. JVP appears mildly elevated.
+
+DR. OKONKWO [to resident]: Alright, we need to move quickly. Differential here is broad — I'm most concerned about acute coronary syndrome versus pulmonary embolism, given the acute onset, the recent prolonged immobilization from the car trip, the calf tenderness, and the hypoxia. The atrial fib and CKD complicate both the workup and management. Let's get a 12-lead ECG stat, troponin I — I see the initial was 0.08 so borderline — CBC, BMP, coags with INR, BNP, and a D-dimer. Start her on two liters nasal cannula and let's get the SpO2 up. Do NOT give heparin yet — she's already on warfarin and her INR was 2.6 on arrival, so she's anticoagulated. Hold off on nitroglycerin too until we see the ECG — I want to rule out a right ventricular infarct first.
+
+RESIDENT DR. CHEN: Got it. ECG is printing now. — ECG shows atrial fibrillation with rapid ventricular response at 114, ST-segment depression in leads V4 through V6, no ST elevation. No right-sided changes.
+
+DR. OKONKWO: Okay, no STEMI and no RV involvement. The ST depression could be demand ischemia from the tachycardia, or it could be an NSTEMI. With the borderline troponin, I want a repeat troponin in three hours for delta. Go ahead and give sublingual nitro now — 0.4 milligrams — and let's see if the chest pain responds.
+
+MARIA GARCIA: Doctor, I should mention — I took one of my old nitroglycerin tablets at home before calling 911. It didn't help much.
+
+DR. OKONKWO: Wait — earlier you said the pain started while you were watching TV and you came straight in. Did you take nitroglycerin at home before the ambulance arrived?
+
+MARIA GARCIA: Yes, sorry. I'm a little confused with everything happening. I did take one at home. It took the edge off for maybe five minutes and then the pain came right back.
+
+DR. OKONKWO: Okay, that's very important information. A partial, transient response to nitro. Let's still give another dose here under monitoring. — And let's get that D-dimer. With the prolonged immobilization and calf tenderness, PE is still on my differential. However, given the CKD with eGFR of 34 and the contrast dye allergy, a CT-PA is going to be problematic. We'll need to consider a V/Q scan instead if the D-dimer comes back elevated.
+
+RESIDENT DR. CHEN: D-dimer result just came in — it's 1,840 nanograms per milliliter. Significantly elevated.
+
+DR. OKONKWO: That's four times the upper limit of normal. In a 72-year-old post-immobilization patient with hypoxia and calf tenderness, that's very concerning for PE. Let's order a V/Q scan — nuclear medicine should be able to do it within the hour. Also, I want a bilateral lower-extremity venous duplex to evaluate for DVT in that left leg.
+
+DR. OKONKWO: Mrs. Garcia, we're running some additional tests. The nitro — has it helped the chest pressure at all?
+
+MARIA GARCIA: A little bit, maybe down to a five now. But I still can't breathe well.
+
+DR. OKONKWO: We're going to increase your oxygen to four liters. — Chen, let's also give a one-time dose of IV metoprolol, 5 milligrams, to try to rate-control the afib. Her heart rate is driving up oxygen demand. Check potassium first — with the CKD and furosemide I want to make sure we're not hypokalemic before we push a beta-blocker.
+
+RESIDENT DR. CHEN: Potassium is 4.1, within normal limits. BNP is 450, creatinine 1.9 consistent with her baseline CKD. Hemoglobin 10.2. Pushing the metoprolol now.
+
+DR. OKONKWO: Good. So to frame this for the chart: we're working up a dual-pathway differential — ACS, specifically NSTEMI, being evaluated with serial troponins and cardiology consult, and concurrent PE workup with V/Q scan and lower extremity duplex given the strong Wells score. The contrast allergy and CKD preclude CT-PA. She's therapeutically anticoagulated on warfarin with INR 2.6 so we're not adding heparin. Rate-controlling the afib with IV metoprolol. Monitoring on continuous telemetry. Admit to Cardiac ICU for observation pending results. — Mrs. Garcia, we're going to keep you here tonight while we sort this out. The team upstairs in the ICU is going to take excellent care of you.
+
+MARIA GARCIA: Thank you, Doctor. I'm scared but I trust you all.
+
+DR. OKONKWO: You're in the right place. We're going to figure out exactly what's going on and take care of it.

data/transcripts/medium.txt

@@ -0,0 +1,41 @@
+DR. NAKAMURA: Good afternoon, Robert. It's been about three months since your last visit. How have things been going with the diabetes and the blood pressure?
+
+ROBERT SMITH: Afternoon, Doc. Honestly, it's been a mixed bag. I've been pretty good about taking the metformin and the lisinopril, but I ran out of the atorvastatin for about two weeks last month because I forgot to call in the refill.
+
+DR. NAKAMURA: Okay, that happens. We'll make a note of that. How about your blood sugars — have you been checking at home?
+
+ROBERT SMITH: Yeah, I check fasting most mornings. They've been running between 140 and 170. I had one reading that was 198 after a birthday dinner, but I figured that was a one-off.
+
+DR. NAKAMURA: Those fasting numbers are still higher than we'd like. Ideally we want them under 130 fasting. I have your recent lab results here — your HbA1c came back at 7.8 percent, which is up from 7.2 three months ago. That tells me your average blood sugar has been creeping up over the past few months.
+
+ROBERT SMITH: That's not great. I was hoping it would hold steady or maybe come down a little.
+
+DR. NAKAMURA: I understand. Let's talk about what might be contributing. You mentioned the birthday dinner — how has your diet been overall? Any changes?
+
+ROBERT SMITH: Well, my wife and I started eating out more. There's a new barbecue place near us, and we've probably been going once or twice a week. I know the portions are huge and the sides are all carbs — mac and cheese, cornbread, baked beans. At home I've been doing okay, but not as strict as I was.
+
+DR. NAKAMURA: That could definitely be a factor. Restaurant meals, especially barbecue with those sides, can have a significant glycemic impact. I'm not going to tell you to never eat out, but I'd like you to try limiting it to once a week, and when you do go, opt for a side salad or steamed vegetables instead of two starchy sides. Would that feel manageable?
+
+ROBERT SMITH: Yeah, I think so. My wife's been on me about it too, so she'll be happy to hear that.
+
+DR. NAKAMURA: Good, teamwork helps. Now, given that the HbA1c has gone up despite being on metformin 1000 twice daily, I think it's time to consider adding a second medication. I'd like to start you on a low dose of glipizide — 5 milligrams once daily with breakfast. It works differently from metformin; it helps your pancreas release more insulin. The main thing to watch for is low blood sugar, so if you feel shaky, sweaty, or lightheaded, check your sugar and have a snack.
+
+ROBERT SMITH: Is that the one that can cause weight gain? I've been trying to keep my weight stable.
+
+DR. NAKAMURA: It can cause modest weight gain in some people, yes. We'll monitor that closely. If weight becomes an issue, there are other classes we can consider, like an SGLT2 inhibitor, which can actually promote weight loss. But let's start here since it's well-studied and affordable on your insurance plan.
+
+ROBERT SMITH: Okay. What about the blood pressure? My home readings have been around 135 over 85 most days.
+
+DR. NAKAMURA: Let me check it here. — I'm getting 142 over 88. That's a bit above target; we want you under 130 over 80 given your diabetes. The lisinopril at 20 milligrams has been tolerable for you — no cough, no dizziness?
+
+ROBERT SMITH: No, nothing like that.
+
+DR. NAKAMURA: Good. I'd like to increase the lisinopril to 40 milligrams daily and see if that brings us closer to goal. Also, and this ties back to the diet — cutting back on the restaurant meals will help the blood pressure too, since those foods tend to be very high in sodium. Your creatinine is 1.1 and eGFR is 78, so kidney function looks stable, which is reassuring. LDL came back at 102 — not bad, but given the two-week gap on the statin, I want to make sure you stay consistent. Under 100 is our target for you.
+
+ROBERT SMITH: Got it. I already set up auto-refills at the pharmacy so that shouldn't happen again.
+
+DR. NAKAMURA: Perfect. So to summarize the plan: continue metformin 1000 twice daily, add glipizide 5 milligrams with breakfast, increase lisinopril from 20 to 40 milligrams daily, continue atorvastatin 40 milligrams daily with no gaps, cut restaurant meals to once weekly with healthier side choices, and I'll see you back in three months with a repeat HbA1c and a fasting lipid panel. Sound good?
+
+ROBERT SMITH: Sounds like a plan. Thanks, Doc.
+
+DR. NAKAMURA: You're doing the right things by showing up and staying engaged, Robert. We'll get these numbers where we want them.

environment/__init__.py

@@ -0,0 +1,13 @@
+"""Clinical Note Scribe environment package."""
+
+from .models import Observation, Action, SOAPNote, Reward, EnvironmentState
+from .env import ClinicalNoteScribeEnv
+
+__all__ = [
+    "Observation",
+    "Action",
+    "SOAPNote",
+    "Reward",
+    "EnvironmentState",
+    "ClinicalNoteScribeEnv",
+]

environment/env.py

@@ -0,0 +1,383 @@
+"""ClinicalNoteScribeEnv — core environment loop.
+
+Implements the ``reset() → Observation``, ``step(Action) → (Observation, Reward, bool, dict)``,
+and ``state() → EnvironmentState`` interface required by the OpenEnv spec.
+
+Structured logging
+------------------
+Every episode emits exactly three kinds of JSON log lines to **stdout**:
+
+- ``{"event": "START", "task_id": "...", "timestamp": ...}``
+- ``{"event": "STEP",  "step": N, "action_type": "...", "reward": R}``
+- ``{"event": "END",   "task_id": "...", "final_score": S}``
+
+The OpenEnv validator scrapes ``[START]``, ``[STEP]``, ``[END]`` keywords.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+from environment.models import Action, EnvironmentState, Observation, Reward, SOAPNote
+from environment.reward import compute_reward
+from environment.tasks import GRADER_REGISTRY, TASK_REGISTRY
+
+logger = logging.getLogger("clinical_note_scribe")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _load_transcript(transcript_path: str) -> str:
+    """Load a transcript text file from *project-root-relative* path."""
+    base = Path(__file__).resolve().parent.parent  # clinical-note-scribe/
+    full_path = base / transcript_path
+    if full_path.exists():
+        return full_path.read_text(encoding="utf-8")
+    return f"[Transcript file not found: {transcript_path}]"
+
+
+def _log_event(event: str, **kwargs: Any) -> None:
+    """Emit a structured JSON log line to stdout via the logger."""
+    payload: dict[str, Any] = {"event": event, "timestamp": time.time()}
+    payload.update(kwargs)
+    logger.info(json.dumps(payload))
+
+
+def _soap_to_text(soap: SOAPNote) -> str:
+    """Flatten a SOAPNote into a readable multi-line string."""
+    return (
+        f"S: {soap.subjective}\n"
+        f"O: {soap.objective}\n"
+        f"A: {soap.assessment}\n"
+        f"P: {soap.plan}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Main environment class
+# ---------------------------------------------------------------------------
+
+class ClinicalNoteScribeEnv:
+    """Open-environment wrapper for the clinical note-scribe tasks.
+
+    Lifecycle
+    ---------
+    1. ``env.reset(task_id)``  → returns initial ``Observation``
+    2. ``env.step(action)``    → returns ``(Observation, Reward, done, info)``
+    3. ``env.state()``         → returns full ``EnvironmentState`` snapshot
+
+    Parameters
+    ----------
+    clarify_answers_path:
+        Project-root-relative path to the clarification lookup JSON.
+    """
+
+    def __init__(
+        self,
+        clarify_answers_path: str = "data/clarify_answers.json",
+    ) -> None:
+        self._clarify_answers: dict[str, str] = {}
+        base = Path(__file__).resolve().parent.parent
+        ca_path = base / clarify_answers_path
+        if ca_path.exists():
+            self._clarify_answers = json.loads(ca_path.read_text(encoding="utf-8"))
+
+        # Episode state (initialised properly in reset())
+        self._task: dict[str, Any] = {}
+        self._task_id: str = ""
+        self._transcript: str = ""
+        self._patient_context: dict[str, Any] = {}
+        self._max_steps: int = 10
+        self._step_count: int = 0
+        self._done: bool = True
+        self._current_draft: str | None = None
+        self._errors_so_far: list[str] = []
+        self._last_reward: Reward | None = None
+        self._last_observation: Observation | None = None
+
+    # --------------------------------------------------------------------- #
+    # Public API
+    # --------------------------------------------------------------------- #
+
+    def reset(self, task_id: str | None = None) -> Observation:
+        """Start (or restart) an episode for the given *task_id*.
+
+        Parameters
+        ----------
+        task_id:
+            One of the keys in ``TASK_REGISTRY``.  When ``None`` the first
+            registered task is used.
+
+        Returns
+        -------
+        Observation
+            The initial observation for the episode.
+
+        Raises
+        ------
+        ValueError
+            If *task_id* is not found in the registry.
+        """
+        if task_id is None:
+            task_id = next(iter(TASK_REGISTRY))
+
+        if task_id not in TASK_REGISTRY:
+            available = ", ".join(TASK_REGISTRY.keys())
+            raise ValueError(
+                f"Unknown task_id '{task_id}'. Available: {available}"
+            )
+
+        self._task = TASK_REGISTRY[task_id]
+        self._task_id = task_id
+        self._transcript = _load_transcript(self._task["transcript_file"])
+        self._patient_context = self._task.get("patient_context", {})
+        self._max_steps = self._task.get("max_steps", 10)
+        self._step_count = 0
+        self._done = False
+        self._current_draft = None
+        self._errors_so_far = []
+        self._last_reward = None
+
+        _log_event("START", task_id=self._task_id)
+
+        obs = self._build_observation()
+        self._last_observation = obs
+        return obs
+
+    def step(self, action: Action) -> tuple[Observation, Reward, bool, dict]:
+        """Execute one agent action and return the resulting observation, reward,
+        done flag, and info dict.
+
+        Parameters
+        ----------
+        action:
+            The agent's chosen action.
+
+        Returns
+        -------
+        tuple[Observation, Reward, bool, dict]
+        """
+        if self._done:
+            raise RuntimeError(
+                "Episode is done. Call reset() before stepping again."
+            )
+
+        self._step_count += 1
+        info: dict[str, Any] = {}
+
+        # ---- dispatch by action type ----
+        if action.action_type == "submit_note":
+            reward = self._handle_submit(action, info)
+        elif action.action_type == "request_clarify":
+            reward = self._handle_clarify(action, info)
+        elif action.action_type == "revise_section":
+            reward = self._handle_revise(action, info)
+        else:
+            # Should never happen thanks to the Literal type, but be safe
+            self._errors_so_far.append(
+                f"Unknown action_type: {action.action_type}"
+            )
+            reward = compute_reward(
+                action,
+                grader_score=0.0,
+                step_count=self._step_count,
+                errors_so_far=self._errors_so_far,
+                done=False,
+                info={"error": "bad_action"},
+            )
+
+        # ---- enforce max-step termination ----
+        if self._step_count >= self._max_steps and not self._done:
+            self._done = True
+            reward = Reward(
+                value=reward.value,
+                signals=reward.signals,
+                done=True,
+                info={**reward.info, "termination_reason": "max_steps_reached"},
+            )
+
+        self._last_reward = reward
+
+        _log_event(
+            "STEP",
+            step=self._step_count,
+            action_type=action.action_type,
+            reward=reward.value,
+        )
+
+        if self._done:
+            _log_event(
+                "END",
+                task_id=self._task_id,
+                final_score=reward.value,
+            )
+
+        obs = self._build_observation()
+        self._last_observation = obs
+        return obs, reward, self._done, info
+
+    def state(self) -> EnvironmentState:
+        """Return the full internal state snapshot."""
+        return EnvironmentState(
+            task_id=self._task_id,
+            step_count=self._step_count,
+            max_steps=self._max_steps,
+            done=self._done,
+            current_draft=self._current_draft,
+            errors_so_far=list(self._errors_so_far),
+            last_reward=self._last_reward,
+            observation=self._last_observation,
+        )
+
+    # --------------------------------------------------------------------- #
+    # Action handlers
+    # --------------------------------------------------------------------- #
+
+    def _handle_submit(self, action: Action, info: dict) -> Reward:
+        """Process a ``submit_note`` action."""
+        if action.soap_note is None:
+            error = "submit_note requires a non-null soap_note."
+            self._errors_so_far.append(error)
+            return compute_reward(
+                action,
+                grader_score=0.0,
+                step_count=self._step_count,
+                errors_so_far=self._errors_so_far,
+                done=False,
+                info={"error": error},
+            )
+
+        self._current_draft = _soap_to_text(action.soap_note)
+        self._done = True
+
+        # Attempt to grade via the task-specific grader
+        grader = GRADER_REGISTRY.get(self._task_id)
+        if grader is None:
+            info["warning"] = "No grader registered; returning default reward."
+            return compute_reward(
+                action,
+                grader_score=0.5,
+                step_count=self._step_count,
+                errors_so_far=self._errors_so_far,
+                done=True,
+                info=info,
+            )
+
+        try:
+            raw_signals = grader(action.soap_note, self._task)
+            # Grader returns a signals dict; extract a single scalar score
+            # as the mean of its values for use as grader_score.
+            grader_score = (
+                sum(raw_signals.values()) / len(raw_signals)
+                if raw_signals else 0.0
+            )
+            info["grader_signals"] = raw_signals
+        except NotImplementedError:
+            info["warning"] = "Grader not yet implemented; returning placeholder."
+            grader_score = 0.5
+
+        return compute_reward(
+            action,
+            grader_score=grader_score,
+            step_count=self._step_count,
+            errors_so_far=self._errors_so_far,
+            done=True,
+            info=info,
+        )
+
+    def _handle_clarify(self, action: Action, info: dict) -> Reward:
+        """Process a ``request_clarify`` action."""
+        question = (action.clarify_question or "").strip()
+        if not question:
+            error = "request_clarify requires a non-empty clarify_question."
+            self._errors_so_far.append(error)
+            return compute_reward(
+                action,
+                grader_score=0.0,
+                step_count=self._step_count,
+                errors_so_far=self._errors_so_far,
+                done=False,
+                info={"error": error},
+            )
+
+        # Lookup a canned answer (case-insensitive key match)
+        answer = self._clarify_answers.get(question.lower())
+        if answer:
+            info["clarify_answer"] = answer
+        else:
+            info["clarify_answer"] = (
+                "No additional information available for that question."
+            )
+
+        # Clarification steps earn no grader_score; step_penalty accrues naturally
+        return compute_reward(
+            action,
+            grader_score=0.0,
+            step_count=self._step_count,
+            errors_so_far=self._errors_so_far,
+            done=False,
+            info=info,
+        )
+
+    def _handle_revise(self, action: Action, info: dict) -> Reward:
+        """Process a ``revise_section`` action."""
+        if action.section is None or action.revision_text is None:
+            error = "revise_section requires both 'section' and 'revision_text'."
+            self._errors_so_far.append(error)
+            return compute_reward(
+                action,
+                grader_score=0.0,
+                step_count=self._step_count,
+                errors_so_far=self._errors_so_far,
+                done=False,
+                info={"error": error},
+            )
+
+        # If there is an existing draft, patch the requested section
+        if self._current_draft:
+            lines = self._current_draft.split("\n")
+            prefix = f"{action.section}: "
+            patched = False
+            for i, line in enumerate(lines):
+                if line.startswith(prefix):
+                    lines[i] = f"{prefix}{action.revision_text}"
+                    patched = True
+                    break
+            if patched:
+                self._current_draft = "\n".join(lines)
+            else:
+                self._current_draft += f"\n{prefix}{action.revision_text}"
+        else:
+            self._current_draft = f"{action.section}: {action.revision_text}"
+
+        info["revised_section"] = action.section
+
+        # Revision steps earn no grader_score; deductions still apply
+        return compute_reward(
+            action,
+            grader_score=0.0,
+            step_count=self._step_count,
+            errors_so_far=self._errors_so_far,
+            done=False,
+            info=info,
+        )
+
+    # --------------------------------------------------------------------- #
+    # Internal helpers
+    # --------------------------------------------------------------------- #
+
+    def _build_observation(self) -> Observation:
+        return Observation(
+            transcript=self._transcript,
+            task_id=self._task_id,
+            patient_context=self._patient_context,
+            current_draft=self._current_draft,
+            errors_so_far=list(self._errors_so_far),
+            step_count=self._step_count,
+        )

environment/models.py

@@ -0,0 +1,175 @@
+"""Pydantic v2 models for the Clinical Note Scribe environment.
+
+Defines the typed contracts for observations, actions, rewards,
+and overall environment state used by the OpenEnv spec.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ---------------------------------------------------------------------------
+# Observation — what the agent sees after each step
+# ---------------------------------------------------------------------------
+
+class Observation(BaseModel):
+    """Snapshot of the environment returned to the agent."""
+
+    transcript: str = Field(
+        ...,
+        description="Full doctor–patient transcript for the current task.",
+    )
+    task_id: str = Field(
+        ...,
+        description="Unique identifier for the task (e.g. 'easy_routine_checkup').",
+    )
+    patient_context: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Structured patient demographics and history.",
+    )
+    current_draft: Optional[str] = Field(
+        default=None,
+        description="The agent's most recent SOAP-note draft, if any.",
+    )
+    errors_so_far: list[str] = Field(
+        default_factory=list,
+        description="Accumulated error/feedback messages from prior steps.",
+    )
+    step_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of steps taken in the current episode.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# SOAPNote — structured clinical note
+# ---------------------------------------------------------------------------
+
+class SOAPNote(BaseModel):
+    """Standard SOAP clinical-note format."""
+
+    subjective: str = Field(
+        ...,
+        description="Patient's self-reported symptoms and history.",
+    )
+    objective: str = Field(
+        ...,
+        description="Clinician's measurable findings (vitals, exam, labs).",
+    )
+    assessment: str = Field(
+        ...,
+        description="Clinician's diagnosis or differential.",
+    )
+    plan: str = Field(
+        ...,
+        description="Treatment plan, follow-ups, and prescriptions.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Action — what the agent can do
+# ---------------------------------------------------------------------------
+
+class Action(BaseModel):
+    """An action the agent submits to the environment."""
+
+    action_type: Literal["submit_note", "request_clarify", "revise_section"] = Field(
+        ...,
+        description="The kind of action the agent is taking.",
+    )
+
+    # --- submit_note fields ---
+    soap_note: Optional[SOAPNote] = Field(
+        default=None,
+        description="Complete SOAP note (required when action_type == 'submit_note').",
+    )
+
+    # --- revise_section fields ---
+    section: Optional[Literal["S", "O", "A", "P"]] = Field(
+        default=None,
+        description="Which SOAP section to revise (required when action_type == 'revise_section').",
+    )
+    revision_text: Optional[str] = Field(
+        default=None,
+        description="Replacement text for the specified section.",
+    )
+
+    # --- request_clarify fields ---
+    clarify_question: Optional[str] = Field(
+        default=None,
+        description="Free-text question the agent asks for clarification.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Reward — multi-signal feedback
+# ---------------------------------------------------------------------------
+
+class Reward(BaseModel):
+    """Reward returned after each step."""
+
+    value: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Aggregate reward in the range [0.0, 1.0].",
+    )
+    signals: dict[str, float] = Field(
+        default_factory=dict,
+        description="Breakdown of individual reward sub-signals.",
+    )
+    done: bool = Field(
+        ...,
+        description="Whether the episode has ended.",
+    )
+    info: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Auxiliary metadata (e.g. grader diagnostics).",
+    )
+
+
+# ---------------------------------------------------------------------------
+# EnvironmentState — full internal state exposed by state()
+# ---------------------------------------------------------------------------
+
+class EnvironmentState(BaseModel):
+    """Complete snapshot of the environment's internal state."""
+
+    task_id: str = Field(
+        ...,
+        description="Active task identifier.",
+    )
+    step_count: int = Field(
+        default=0,
+        ge=0,
+        description="Steps taken so far in this episode.",
+    )
+    max_steps: int = Field(
+        default=10,
+        ge=1,
+        description="Maximum steps allowed per episode.",
+    )
+    done: bool = Field(
+        default=False,
+        description="Whether the current episode has terminated.",
+    )
+    current_draft: Optional[str] = Field(
+        default=None,
+        description="Latest SOAP-note draft text, if any.",
+    )
+    errors_so_far: list[str] = Field(
+        default_factory=list,
+        description="Accumulated feedback/error messages.",
+    )
+    last_reward: Optional[Reward] = Field(
+        default=None,
+        description="Most recent reward object, if a step has been taken.",
+    )
+    observation: Optional[Observation] = Field(
+        default=None,
+        description="Most recent observation returned to the agent.",
+    )

environment/reward.py

@@ -0,0 +1,197 @@
+"""Multi-signal reward computation for the Clinical Note Scribe environment.
+
+Reward formula (all weights sum to 1.0 before penalties):
+
+  weighted_sum = grader_score       × 0.60   (clinical accuracy from task grader)
+               + conciseness_bonus  × 0.10   (1.0 if note ≤ 400 words, else 0.0)
+               + safe_language_score× 0.15   (1.0 if no unsafe-certainty phrases)
+               + format_valid       × 0.15   (1.0 if SOAP JSON is well-formed)
+
+Deductions (applied after weighted sum):
+  - 0.05 × max(0, step_count - 3)   (penalty for excessive clarification steps)
+  - 0.10 × len(errors_so_far)        (penalty for each invalid action)
+
+Final value is clamped to [0.0, 1.0].
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from environment.models import Action, Reward, SOAPNote
+
+
+# ---------------------------------------------------------------------------
+# Weights
+# ---------------------------------------------------------------------------
+
+W_GRADER      = 0.60
+W_CONCISE     = 0.10
+W_SAFE_LANG   = 0.15
+W_FORMAT      = 0.15
+
+# Deduction constants
+STEP_PENALTY_RATE   = 0.05   # per step beyond FREE_STEPS
+FREE_STEPS          = 3
+ERROR_PENALTY_RATE  = 0.10   # per item in errors_so_far
+
+# Conciseness threshold
+WORD_LIMIT = 400
+
+# Phrases that indicate unsafe clinical certainty
+# (over-confident language that a scribe should avoid in a note)
+_UNSAFE_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(p, re.IGNORECASE)
+    for p in [
+        r"\bpatient definitely has\b",
+        r"\bdiagnosis is certain\b",
+        r"\bno doubt\b",
+        r"\babsolutely confirmed\b",
+        r"\b100%\s+certain\b",
+        r"\bwill definitely\b",
+        r"\bguaranteed to\b",
+        r"\bcannot be\s+\w+\s+else\b",
+        r"\bwithout question\b",
+        r"\bthis is clearly\b",
+    ]
+]
+
+
+# ---------------------------------------------------------------------------
+# Sub-signal helpers
+# ---------------------------------------------------------------------------
+
+def _conciseness_bonus(soap_note: Optional[SOAPNote]) -> float:
+    """Return 1.0 if the total SOAP note word count is at or below WORD_LIMIT."""
+    if soap_note is None:
+        return 0.0
+    text = " ".join([
+        soap_note.subjective,
+        soap_note.objective,
+        soap_note.assessment,
+        soap_note.plan,
+    ])
+    word_count = len(text.split())
+    return 1.0 if word_count <= WORD_LIMIT else 0.0
+
+
+def _safe_language_score(soap_note: Optional[SOAPNote]) -> float:
+    """Return 1.0 if no unsafe-certainty phrases are found in the SOAP note."""
+    if soap_note is None:
+        return 1.0   # no note submitted → no unsafe language
+    text = " ".join([
+        soap_note.subjective,
+        soap_note.objective,
+        soap_note.assessment,
+        soap_note.plan,
+    ])
+    for pattern in _UNSAFE_PATTERNS:
+        if pattern.search(text):
+            return 0.0
+    return 1.0
+
+
+def _format_valid(action: Action) -> float:
+    """Return 1.0 if the submitted note has all required non-empty SOAP fields.
+
+    This acts as a lightweight structural / «JSON well-formed» check:
+    each of S, O, A, P must be a non-empty string, and the action_type
+    must be ``submit_note``.
+    """
+    if action.action_type != "submit_note":
+        return 1.0   # non-submission actions are not graded on format
+    if action.soap_note is None:
+        return 0.0
+    soap = action.soap_note
+    fields = [soap.subjective, soap.objective, soap.assessment, soap.plan]
+    if all(isinstance(f, str) and f.strip() for f in fields):
+        return 1.0
+    return 0.0
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def compute_reward(
+    action: Action,
+    grader_score: float,
+    step_count: int,
+    errors_so_far: list[str],
+    *,
+    done: bool = False,
+    info: Optional[dict[str, Any]] = None,
+) -> Reward:
+    """Compute the multi-signal reward for a completed step.
+
+    Parameters
+    ----------
+    action:
+        The action that was just executed.
+    grader_score:
+        Clinical-accuracy score returned by the task-specific grader (0.0–1.0).
+        Use 0.0 for non-submission actions.
+    step_count:
+        Total number of steps taken so far in the episode (including this one).
+    errors_so_far:
+        List of error messages accumulated during the episode.
+    done:
+        Whether the episode ended with this step.
+    info:
+        Optional auxiliary metadata dict to include in the Reward.
+
+    Returns
+    -------
+    Reward
+        Fully populated Reward with ``value`` and ``signals`` breakdown.
+    """
+    grader_score = max(0.0, min(1.0, grader_score))
+
+    # ---- per-signal scores ----
+    conciseness  = _conciseness_bonus(action.soap_note)
+    safe_lang    = _safe_language_score(action.soap_note)
+    fmt          = _format_valid(action)
+
+    # ---- weighted sum ----
+    weighted = (
+        grader_score * W_GRADER
+        + conciseness  * W_CONCISE
+        + safe_lang    * W_SAFE_LANG
+        + fmt          * W_FORMAT
+    )
+
+    # ---- deductions ----
+    extra_steps   = max(0, step_count - FREE_STEPS)
+    step_penalty  = extra_steps * STEP_PENALTY_RATE
+    error_penalty = len(errors_so_far) * ERROR_PENALTY_RATE
+
+    raw = weighted - step_penalty - error_penalty
+
+    # ---- clamp ----
+    value = max(0.0, min(1.0, raw))
+
+    signals: dict[str, float] = {
+        # positive contributions
+        "grader_score":        round(grader_score * W_GRADER,   4),
+        "conciseness_bonus":   round(conciseness  * W_CONCISE,  4),
+        "safe_language_score": round(safe_lang     * W_SAFE_LANG, 4),
+        "format_valid":        round(fmt           * W_FORMAT,   4),
+        # deductions (stored as negative numbers for clarity)
+        "step_penalty":        round(-step_penalty,  4),
+        "error_penalty":       round(-error_penalty, 4),
+        # raw sub-signal values (unweighted, for introspection)
+        "_grader_score_raw":        round(grader_score, 4),
+        "_conciseness_raw":         round(conciseness,  4),
+        "_safe_language_raw":       round(safe_lang,    4),
+        "_format_valid_raw":        round(fmt,          4),
+        "_extra_steps":             float(extra_steps),
+        "_error_count":             float(len(errors_so_far)),
+    }
+
+    return Reward(
+        value=round(value, 4),
+        signals=signals,
+        done=done,
+        info=info or {},
+    )

environment/tasks/__init__.py

@@ -0,0 +1,22 @@
+"""Task definitions for easy, medium, and hard scenarios."""
+
+from .task_easy import EASY_TASK, grade_easy
+from .task_medium import MEDIUM_TASK, grade_medium
+from .task_hard import HARD_TASK, grade_hard
+
+TASK_REGISTRY: dict[str, dict] = {
+    EASY_TASK["task_id"]: EASY_TASK,
+    MEDIUM_TASK["task_id"]: MEDIUM_TASK,
+    HARD_TASK["task_id"]: HARD_TASK,
+}
+
+GRADER_REGISTRY: dict[str, callable] = {
+    EASY_TASK["task_id"]: grade_easy,
+    MEDIUM_TASK["task_id"]: grade_medium,
+    HARD_TASK["task_id"]: grade_hard,
+}
+
+__all__ = [
+    "TASK_REGISTRY",
+    "GRADER_REGISTRY",
+]

environment/tasks/task_easy.py

@@ -0,0 +1,57 @@
+"""Easy task — routine check-up.
+
+Grader is intentionally left unimplemented.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from environment.models import SOAPNote
+
+
+# ---------------------------------------------------------------------------
+# Task definition
+# ---------------------------------------------------------------------------
+
+EASY_TASK: dict[str, Any] = {
+    "task_id": "easy_routine_checkup",
+    "description": "Generate a SOAP note for a routine annual check-up visit.",
+    "transcript_file": "data/transcripts/easy.txt",
+    "patient_context": {
+        "patient_id": "P-1001",
+        "name": "Jane Doe",
+        "age": 34,
+        "sex": "F",
+        "known_conditions": [],
+        "current_medications": [],
+        "allergies": ["Penicillin"],
+    },
+    "max_steps": 5,
+}
+
+
+# ---------------------------------------------------------------------------
+# Grader (not yet implemented)
+# ---------------------------------------------------------------------------
+
+def grade_easy(soap_note: SOAPNote, task: dict[str, Any]) -> dict[str, float]:
+    """Score a submitted SOAP note against the easy-task rubric.
+
+    Parameters
+    ----------
+    soap_note:
+        The agent's submitted clinical note.
+    task:
+        The task definition dict (``EASY_TASK``).
+
+    Returns
+    -------
+    dict mapping signal names → float scores in [0, 1].
+
+    Raises
+    ------
+    NotImplementedError
+        Grader has not been implemented yet.
+    """
+    raise NotImplementedError("Easy-task grader is not yet implemented.")

environment/tasks/task_hard.py

@@ -0,0 +1,86 @@
+"""Hard task — complex ER visit.
+
+Grader is intentionally left unimplemented.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from environment.models import SOAPNote
+
+
+# ---------------------------------------------------------------------------
+# Task definition
+# ---------------------------------------------------------------------------
+
+HARD_TASK: dict[str, Any] = {
+    "task_id": "hard_complex_er_visit",
+    "description": (
+        "Generate a SOAP note for a complex emergency-room visit involving "
+        "chest pain, polytrauma assessment, and multiple co-morbidities."
+    ),
+    "transcript_file": "data/transcripts/hard.txt",
+    "patient_context": {
+        "patient_id": "P-3782",
+        "name": "Maria Garcia",
+        "age": 72,
+        "sex": "F",
+        "known_conditions": [
+            "Coronary Artery Disease",
+            "Atrial Fibrillation",
+            "Chronic Kidney Disease Stage 3",
+            "Osteoarthritis",
+        ],
+        "current_medications": [
+            "Aspirin 81 mg daily",
+            "Warfarin 5 mg daily",
+            "Metoprolol 50 mg BID",
+            "Furosemide 40 mg daily",
+            "Amlodipine 5 mg daily",
+        ],
+        "allergies": ["Sulfa drugs", "Contrast dye"],
+        "recent_labs": {
+            "troponin_I": "0.08 ng/mL",
+            "BNP": "450 pg/mL",
+            "creatinine": "1.9 mg/dL",
+            "eGFR": "34 mL/min",
+            "INR": "2.6",
+            "hemoglobin": "10.2 g/dL",
+        },
+        "vitals_on_arrival": {
+            "BP": "168/94 mmHg",
+            "HR": "112 bpm (irregular)",
+            "RR": "22 breaths/min",
+            "SpO2": "91% on room air",
+            "Temp": "37.2°C",
+        },
+    },
+    "max_steps": 10,
+}
+
+
+# ---------------------------------------------------------------------------
+# Grader (not yet implemented)
+# ---------------------------------------------------------------------------
+
+def grade_hard(soap_note: SOAPNote, task: dict[str, Any]) -> dict[str, float]:
+    """Score a submitted SOAP note against the hard-task rubric.
+
+    Parameters
+    ----------
+    soap_note:
+        The agent's submitted clinical note.
+    task:
+        The task definition dict (``HARD_TASK``).
+
+    Returns
+    -------
+    dict mapping signal names → float scores in [0, 1].
+
+    Raises
+    ------
+    NotImplementedError
+        Grader has not been implemented yet.
+    """
+    raise NotImplementedError("Hard-task grader is not yet implemented.")

environment/tasks/task_medium.py

@@ -0,0 +1,68 @@
+"""Medium task — chronic disease follow-up.
+
+Grader is intentionally left unimplemented.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from environment.models import SOAPNote
+
+
+# ---------------------------------------------------------------------------
+# Task definition
+# ---------------------------------------------------------------------------
+
+MEDIUM_TASK: dict[str, Any] = {
+    "task_id": "medium_chronic_disease_followup",
+    "description": "Generate a SOAP note for a Type 2 Diabetes follow-up visit.",
+    "transcript_file": "data/transcripts/medium.txt",
+    "patient_context": {
+        "patient_id": "P-2045",
+        "name": "Robert Smith",
+        "age": 58,
+        "sex": "M",
+        "known_conditions": ["Type 2 Diabetes Mellitus", "Hypertension"],
+        "current_medications": [
+            "Metformin 1000 mg BID",
+            "Lisinopril 20 mg daily",
+            "Atorvastatin 40 mg daily",
+        ],
+        "allergies": [],
+        "recent_labs": {
+            "HbA1c": "7.8%",
+            "fasting_glucose": "156 mg/dL",
+            "creatinine": "1.1 mg/dL",
+            "eGFR": "78 mL/min",
+            "LDL": "102 mg/dL",
+        },
+    },
+    "max_steps": 8,
+}
+
+
+# ---------------------------------------------------------------------------
+# Grader (not yet implemented)
+# ---------------------------------------------------------------------------
+
+def grade_medium(soap_note: SOAPNote, task: dict[str, Any]) -> dict[str, float]:
+    """Score a submitted SOAP note against the medium-task rubric.
+
+    Parameters
+    ----------
+    soap_note:
+        The agent's submitted clinical note.
+    task:
+        The task definition dict (``MEDIUM_TASK``).
+
+    Returns
+    -------
+    dict mapping signal names → float scores in [0, 1].
+
+    Raises
+    ------
+    NotImplementedError
+        Grader has not been implemented yet.
+    """
+    raise NotImplementedError("Medium-task grader is not yet implemented.")

inference.py

@@ -0,0 +1,324 @@
+"""Baseline inference script for the Clinical Note Scribe environment.
+
+Runs all three tasks (easy → medium → hard) sequentially using an
+OpenAI-compatible API to generate SOAP notes from doctor–patient transcripts.
+
+Environment variables
+---------------------
+OPENAI_API_KEY   – API key for the model provider
+API_BASE_URL     – Base URL for the OpenAI-compatible endpoint (default: https://api.openai.com/v1)
+MODEL_NAME       – Model identifier to use (default: gpt-4o-mini)
+
+Usage::
+
+    python inference.py
+
+Designed to complete in under 20 minutes on 2 vCPU / 8 GB RAM.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import time
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Bootstrap logging BEFORE importing environment modules so the root logger
+# is configured and child loggers (clinical_note_scribe.*) propagate cleanly.
+# ---------------------------------------------------------------------------
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+logger = logging.getLogger("inference")
+
+# ---------------------------------------------------------------------------
+# Environment imports (after logging is configured)
+# ---------------------------------------------------------------------------
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from environment import ClinicalNoteScribeEnv, Action, SOAPNote  # noqa: E402
+from environment.tasks import TASK_REGISTRY                       # noqa: E402
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+API_KEY      = os.environ.get("OPENAI_API_KEY", "")
+API_BASE_URL = os.environ.get("API_BASE_URL", "https://api.openai.com/v1")
+MODEL_NAME   = os.environ.get("MODEL_NAME", "gpt-4o-mini")
+
+TASK_IDS = list(TASK_REGISTRY.keys())  # deterministic order
+
+# Maximum tokens for the model response — keeps latency low
+MAX_TOKENS = 1024
+
+# ---------------------------------------------------------------------------
+# System prompt
+# ---------------------------------------------------------------------------
+
+SYSTEM_PROMPT = """\
+You are a clinical documentation assistant. Given a doctor–patient transcript \
+and patient context, generate a concise, clinically accurate SOAP note.
+
+RULES:
+1. Use professional medical language.  Avoid over-certain phrasing such as \
+   "patient definitely has", "diagnosis is certain", or "100% certain".
+2. Keep the note concise — aim for under 400 words total across all four sections.
+3. Return your output as a **single valid JSON object** matching this schema exactly:
+
+{
+  "action_type": "submit_note",
+  "soap_note": {
+    "subjective": "<patient's reported symptoms, history, and concerns>",
+    "objective": "<exam findings, vitals, lab results, imaging>",
+    "assessment": "<differential diagnoses and clinical reasoning>",
+    "plan": "<treatment plan, medications, follow-up, referrals>"
+  }
+}
+
+Return ONLY the JSON object.  No markdown fences, no commentary, no extra keys.
+"""
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_user_prompt(transcript: str, patient_context: dict[str, Any]) -> str:
+    """Build the user message containing the transcript and context."""
+    ctx_str = json.dumps(patient_context, indent=2, default=str)
+    return (
+        f"## Patient Context\n```json\n{ctx_str}\n```\n\n"
+        f"## Doctor–Patient Transcript\n```\n{transcript}\n```\n\n"
+        "Generate the SOAP note as a JSON Action object."
+    )
+
+
+def _call_model(user_prompt: str) -> dict[str, Any]:
+    """Call the OpenAI-compatible API and return the parsed JSON action dict.
+
+    Uses ``urllib`` so there is zero dependency on ``openai`` package —
+    this keeps the Docker image small and avoids version conflicts.
+    Falls back to the ``openai`` package if installed.
+    """
+    try:
+        return _call_model_sdk(user_prompt)
+    except ImportError:
+        return _call_model_urllib(user_prompt)
+
+
+def _call_model_sdk(user_prompt: str) -> dict[str, Any]:
+    """Call via the ``openai`` Python SDK."""
+    from openai import OpenAI  # noqa: F811
+
+    client = OpenAI(
+        api_key=API_KEY,
+        base_url=API_BASE_URL,
+    )
+    response = client.chat.completions.create(
+        model=MODEL_NAME,
+        messages=[
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user",   "content": user_prompt},
+        ],
+        max_tokens=MAX_TOKENS,
+        temperature=0.2,
+    )
+    raw = response.choices[0].message.content.strip()
+    return _parse_json(raw)
+
+
+def _call_model_urllib(user_prompt: str) -> dict[str, Any]:
+    """Fallback: call the API with ``urllib`` (no extra dependencies)."""
+    import urllib.request
+
+    url = f"{API_BASE_URL.rstrip('/')}/chat/completions"
+    payload = json.dumps({
+        "model": MODEL_NAME,
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user",   "content": user_prompt},
+        ],
+        "max_tokens": MAX_TOKENS,
+        "temperature": 0.2,
+    }).encode()
+
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {API_KEY}",
+        },
+    )
+    with urllib.request.urlopen(req, timeout=120) as resp:
+        body = json.loads(resp.read())
+
+    raw = body["choices"][0]["message"]["content"].strip()
+    return _parse_json(raw)
+
+
+def _parse_json(raw: str) -> dict[str, Any]:
+    """Parse the model's raw text output into a dict, tolerating markdown fences."""
+    # Strip markdown code fences if present
+    cleaned = raw
+    if cleaned.startswith("```"):
+        # remove opening fence (possibly ```json)
+        first_newline = cleaned.index("\n")
+        cleaned = cleaned[first_newline + 1:]
+    if cleaned.endswith("```"):
+        cleaned = cleaned[: -3]
+    cleaned = cleaned.strip()
+
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError as exc:
+        logger.error("Failed to parse model output as JSON: %s", exc)
+        logger.error("Raw output:\n%s", raw)
+        raise
+
+
+def _log_event(event: str, **kwargs: Any) -> None:
+    """Emit a structured JSON log line."""
+    payload: dict[str, Any] = {"event": event, "timestamp": time.time()}
+    payload.update(kwargs)
+    logger.info(json.dumps(payload, default=str))
+
+
+# ---------------------------------------------------------------------------
+# Main loop
+# ---------------------------------------------------------------------------
+
+
+def run_all_tasks() -> list[dict[str, Any]]:
+    """Run every registered task and return a list of result dicts."""
+    env = ClinicalNoteScribeEnv()
+    results: list[dict[str, Any]] = []
+
+    for task_id in TASK_IDS:
+        logger.info("")
+        logger.info("=" * 60)
+        logger.info("  TASK: %s", task_id)
+        logger.info("=" * 60)
+
+        t0 = time.time()
+        _log_event("INFERENCE_START", task_id=task_id)
+
+        # ---- reset ----
+        obs = env.reset(task_id)
+        logger.info("  Transcript length : %d chars", len(obs.transcript))
+        logger.info("  Patient context keys: %s", list(obs.patient_context.keys()))
+
+        # ---- generate SOAP note via LLM ----
+        user_prompt = _build_user_prompt(obs.transcript, obs.patient_context)
+        logger.info("  Calling model (%s) ...", MODEL_NAME)
+
+        try:
+            action_dict = _call_model(user_prompt)
+        except Exception as exc:
+            logger.error("  Model call failed: %s", exc)
+            results.append({
+                "task_id": task_id,
+                "score": 0.0,
+                "error": str(exc),
+                "elapsed_s": round(time.time() - t0, 2),
+            })
+            _log_event("INFERENCE_ERROR", task_id=task_id, error=str(exc))
+            continue
+
+        # ---- validate and create Action ----
+        try:
+            action = Action(**action_dict)
+        except Exception as exc:
+            logger.error("  Invalid action schema: %s", exc)
+            logger.error("  Model returned: %s", json.dumps(action_dict, indent=2))
+            results.append({
+                "task_id": task_id,
+                "score": 0.0,
+                "error": f"schema_error: {exc}",
+                "elapsed_s": round(time.time() - t0, 2),
+            })
+            _log_event("INFERENCE_ERROR", task_id=task_id, error=str(exc))
+            continue
+
+        # ---- step (submit) ----
+        obs2, reward, done, info = env.step(action)
+        elapsed = round(time.time() - t0, 2)
+
+        logger.info("  Done: %s  |  Reward: %.4f  |  Elapsed: %.1fs", done, reward.value, elapsed)
+        logger.info("  Signals: %s",
+                     {k: v for k, v in reward.signals.items() if not k.startswith("_")})
+
+        _log_event("INFERENCE_END", task_id=task_id, score=reward.value, elapsed_s=elapsed)
+
+        results.append({
+            "task_id": task_id,
+            "score": reward.value,
+            "elapsed_s": elapsed,
+        })
+
+    return results
+
+
+def _print_summary(results: list[dict[str, Any]]) -> None:
+    """Print a formatted summary table."""
+    logger.info("")
+    logger.info("=" * 60)
+    logger.info("  SUMMARY")
+    logger.info("=" * 60)
+
+    col_task  = max(len("Task"), *(len(r["task_id"]) for r in results))
+    col_score = 7  # "Score" + padding
+    col_time  = 9  # "Time (s)"
+
+    header = f"  {'Task':<{col_task}}  {'Score':>{col_score}}  {'Time (s)':>{col_time}}"
+    sep    = f"  {'-' * col_task}  {'-' * col_score}  {'-' * col_time}"
+    logger.info(header)
+    logger.info(sep)
+
+    total_score = 0.0
+    for r in results:
+        score_str = f"{r['score']:.4f}" if "error" not in r else "ERROR"
+        time_str  = f"{r['elapsed_s']:.1f}"
+        logger.info(f"  {r['task_id']:<{col_task}}  {score_str:>{col_score}}  {time_str:>{col_time}}")
+        total_score += r["score"]
+
+    logger.info(sep)
+    avg = total_score / len(results) if results else 0.0
+    logger.info(f"  {'AVERAGE':<{col_task}}  {avg:>{col_score}.4f}")
+    logger.info("")
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    if not API_KEY:
+        logger.warning(
+            "OPENAI_API_KEY is not set. The model calls will fail unless "
+            "the API endpoint does not require authentication."
+        )
+
+    logger.info("Clinical Note Scribe — Baseline Inference")
+    logger.info("  Model      : %s", MODEL_NAME)
+    logger.info("  API Base   : %s", API_BASE_URL)
+    logger.info("  Tasks      : %s", TASK_IDS)
+    logger.info("")
+
+    start = time.time()
+    results = run_all_tasks()
+    total_elapsed = round(time.time() - start, 2)
+
+    _print_summary(results)
+    logger.info("  Total wall-clock time: %.1fs", total_elapsed)
+
+    _log_event("INFERENCE_COMPLETE", total_elapsed_s=total_elapsed,
+               scores={r["task_id"]: r["score"] for r in results})

openenv.yaml

@@ -0,0 +1,211 @@
+# OpenEnv Environment Specification
+# Clinical Note Scribe — Meta × Hugging Face OpenEnv Hackathon
+
+name: meta-huggingface-hackathon-team-silver-orca
+version: 1.0.0
+description: >
+  An OpenEnv-compliant environment for evaluating AI agents on clinical
+  SOAP-note generation from doctor–patient transcripts. Agents receive a
+  transcript and patient context, then must produce a well-structured,
+  clinically accurate SOAP note through submit, revise, or clarify actions.
+
+# ---------------------------------------------------------------------------
+# Tasks
+# ---------------------------------------------------------------------------
+tasks:
+  - id: easy_routine_checkup
+    description: >
+      Generate a SOAP note for a routine annual check-up visit.
+      6-turn dialogue covering a simple upper respiratory infection
+      and a blood pressure screening.
+    difficulty: easy
+    max_steps: 5
+    grader: grade_easy
+
+  - id: medium_chronic_disease_followup
+    description: >
+      Generate a SOAP note for a Type 2 Diabetes and Hypertension
+      follow-up visit. 14-turn dialogue including medication adjustments
+      (glipizide addition, lisinopril uptitration), HbA1c lab review,
+      and dietary counseling.
+    difficulty: medium
+    max_steps: 8
+    grader: grade_medium
+
+  - id: hard_complex_er_visit
+    description: >
+      Generate a SOAP note for a complex emergency-room visit with
+      overlapping chest pain, shortness of breath, and a possible
+      pulmonary embolism. 20-turn dialogue with differential diagnoses,
+      urgent orders, a patient self-contradiction, and contrast-allergy
+      complications.
+    difficulty: hard
+    max_steps: 10
+    grader: grade_hard
+
+# ---------------------------------------------------------------------------
+# API Endpoints
+# ---------------------------------------------------------------------------
+api:
+  base_url: http://localhost:7860
+  endpoints:
+    reset:
+      method: POST
+      path: /reset
+      request_schema: ResetRequest
+      response_schema: Observation
+      description: Start a new episode for the specified task.
+
+    step:
+      method: POST
+      path: /step
+      request_schema: Action
+      response_schema: StepResponse
+      description: Submit an action and advance the environment by one step.
+
+    state:
+      method: GET
+      path: /state
+      response_schema: EnvironmentState
+      description: Return the full internal environment state without mutation.
+
+    health:
+      method: GET
+      path: /health
+      response_schema: HealthResponse
+      description: Liveness probe; returns {"status":"ok"}.
+
+# ---------------------------------------------------------------------------
+# Schemas (Pydantic v2 models in environment/models.py)
+# ---------------------------------------------------------------------------
+schemas:
+  Observation:
+    fields:
+      - name: transcript
+        type: str
+        description: Full doctor–patient transcript for the current task.
+      - name: task_id
+        type: str
+        description: Unique identifier for the task.
+      - name: patient_context
+        type: "dict[str, Any]"
+        description: Structured patient demographics and history.
+      - name: current_draft
+        type: "Optional[str]"
+        description: The agent's most recent SOAP-note draft, if any.
+      - name: errors_so_far
+        type: "list[str]"
+        description: Accumulated error/feedback messages from prior steps.
+      - name: step_count
+        type: int
+        description: Number of steps taken in the current episode.
+
+  Action:
+    fields:
+      - name: action_type
+        type: "Literal['submit_note','request_clarify','revise_section']"
+        description: The kind of action the agent is taking.
+      - name: soap_note
+        type: "Optional[SOAPNote]"
+        description: Complete SOAP note (required for submit_note).
+      - name: section
+        type: "Optional[Literal['S','O','A','P']]"
+        description: Section to revise (required for revise_section).
+      - name: revision_text
+        type: "Optional[str]"
+        description: Replacement text for the section.
+      - name: clarify_question
+        type: "Optional[str]"
+        description: Clarification question to ask.
+
+  SOAPNote:
+    fields:
+      - name: subjective
+        type: str
+      - name: objective
+        type: str
+      - name: assessment
+        type: str
+      - name: plan
+        type: str
+
+  Reward:
+    fields:
+      - name: value
+        type: float
+        description: "Aggregate reward in [0.0, 1.0]."
+      - name: signals
+        type: "dict[str, float]"
+        description: Breakdown of individual reward sub-signals.
+      - name: done
+        type: bool
+        description: Whether the episode has ended.
+      - name: info
+        type: "dict[str, Any]"
+        description: Auxiliary metadata.
+
+  EnvironmentState:
+    fields:
+      - name: task_id
+        type: str
+      - name: step_count
+        type: int
+      - name: max_steps
+        type: int
+      - name: done
+        type: bool
+      - name: current_draft
+        type: "Optional[str]"
+      - name: errors_so_far
+        type: "list[str]"
+      - name: last_reward
+        type: "Optional[Reward]"
+      - name: observation
+        type: "Optional[Observation]"
+
+# ---------------------------------------------------------------------------
+# Reward function
+# ---------------------------------------------------------------------------
+reward:
+  range: [0.0, 1.0]
+  formula: >
+    weighted_sum = grader_score × 0.60
+                 + conciseness_bonus × 0.10
+                 + safe_language_score × 0.15
+                 + format_valid × 0.15
+    deductions   = 0.05 × max(0, step_count - 3)
+                 + 0.10 × len(errors_so_far)
+    value        = clamp(weighted_sum - deductions, 0.0, 1.0)
+  signals:
+    - grader_score:        "Clinical accuracy from task-specific grader (0–1)"
+    - conciseness_bonus:   "1.0 if SOAP note ≤ 400 words, else 0.0"
+    - safe_language_score: "1.0 if no unsafe-certainty phraseology, else 0.0"
+    - format_valid:        "1.0 if all SOAP fields are non-empty strings"
+    - step_penalty:        "−0.05 per step beyond 3"
+    - error_penalty:       "−0.10 per invalid action error"
+
+# ---------------------------------------------------------------------------
+# Graders
+# ---------------------------------------------------------------------------
+graders:
+  - name: grade_easy
+    file: environment/tasks/task_easy.py
+    function: grade_easy
+
+  - name: grade_medium
+    file: environment/tasks/task_medium.py
+    function: grade_medium
+
+  - name: grade_hard
+    file: environment/tasks/task_hard.py
+    function: grade_hard
+
+# ---------------------------------------------------------------------------
+# Inference
+# ---------------------------------------------------------------------------
+inference:
+  script: inference.py
+  env_vars:
+    - OPENAI_API_KEY
+    - API_BASE_URL
+    - MODEL_NAME

requirements.txt

@@ -0,0 +1,4 @@
+fastapi>=0.110.0
+uvicorn>=0.29.0
+pydantic>=2.7.0
+openai>=1.30.0

server/__init__.py

@@ -0,0 +1 @@
+"""Server package for the Clinical Note Scribe environment."""

server/app.py

@@ -0,0 +1,46 @@
+"""FastAPI application for the Clinical Note Scribe environment.
+
+Run locally::
+
+    uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload
+
+Or via Docker (see ``Dockerfile`` in project root).
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+from fastapi import FastAPI
+
+from server.routes import router
+
+# ---------------------------------------------------------------------------
+# Configure root logging → structured JSON to stdout
+# ---------------------------------------------------------------------------
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    handlers=[logging.StreamHandler(sys.stdout)],
+)
+
+# Silence noisy uvicorn access logs so our structured events stay clean
+logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+# ---------------------------------------------------------------------------
+# Application factory
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="Clinical Note Scribe – OpenEnv",
+    description=(
+        "An OpenEnv-compliant environment for evaluating AI agents on "
+        "clinical SOAP-note generation from doctor–patient transcripts."
+    ),
+    version="0.1.0",
+)
+
+# Mount all routes at root (/)
+app.include_router(router)

server/routes.py

@@ -0,0 +1,154 @@
+"""FastAPI route definitions for the Clinical Note Scribe environment.
+
+Endpoints
+---------
+POST /reset   – start a new episode (takes ``task_id``, returns ``Observation``)
+POST /step    – execute an action   (takes ``Action``,  returns step result)
+GET  /state   – inspect env state   (returns ``EnvironmentState``)
+GET  /health  – liveness probe      (returns ``{"status": "ok"}``)
+
+Structured logging
+------------------
+The underlying ``ClinicalNoteScribeEnv`` already emits ``[START]``, ``[STEP]``,
+and ``[END]`` JSON lines to stdout via Python's ``logging`` module.  This router
+adds a thin request-level log wrapper so every inbound HTTP call is also
+traceable.
+"""
+
+from __future__ import annotations
+
+import logging
+import json
+import time
+from typing import Any, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from environment.models import (
+    Action,
+    EnvironmentState,
+    Observation,
+    Reward,
+)
+from environment.env import ClinicalNoteScribeEnv
+
+logger = logging.getLogger("clinical_note_scribe.server")
+
+
+# ---------------------------------------------------------------------------
+# Singleton environment instance
+# ---------------------------------------------------------------------------
+
+_env = ClinicalNoteScribeEnv()
+
+
+# ---------------------------------------------------------------------------
+# Request / response schemas
+# ---------------------------------------------------------------------------
+
+class ResetRequest(BaseModel):
+    task_id: Optional[str] = Field(
+        default=None,
+        description=(
+            "Task to load. One of: easy_routine_checkup, "
+            "medium_chronic_disease_followup, hard_complex_er_visit. "
+            "Defaults to the first registered task."
+        ),
+    )
+
+
+class StepResponse(BaseModel):
+    observation: Observation
+    reward: Reward
+    done: bool
+    info: dict[str, Any] = Field(default_factory=dict)
+
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _log(event: str, **kwargs: Any) -> None:
+    """Emit a structured JSON log line to stdout."""
+    payload: dict[str, Any] = {"event": event, "timestamp": time.time()}
+    payload.update(kwargs)
+    logger.info(json.dumps(payload, default=str))
+
+
+# ---------------------------------------------------------------------------
+# Router
+# ---------------------------------------------------------------------------
+
+router = APIRouter()
+
+
+@router.post(
+    "/reset",
+    response_model=Observation,
+    summary="Reset the environment and start a new episode",
+)
+async def reset(body: ResetRequest) -> Observation:
+    """Load a task and return the initial ``Observation``.
+
+    The underlying environment emits a ``[START]`` log event.
+    """
+    _log("START", endpoint="/reset", task_id=body.task_id)
+    try:
+        obs = _env.reset(task_id=body.task_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return obs
+
+
+@router.post(
+    "/step",
+    response_model=StepResponse,
+    summary="Submit an action and advance the environment by one step",
+)
+async def step(action: Action) -> StepResponse:
+    """Execute *action* in the current episode.
+
+    The underlying environment emits a ``[STEP]`` log event (and ``[END]``
+    when the episode terminates).
+    """
+    _log("STEP", endpoint="/step", action_type=action.action_type)
+    try:
+        obs, reward, done, info = _env.step(action)
+    except RuntimeError as exc:
+        # e.g. stepping after episode is done without reset
+        raise HTTPException(status_code=409, detail=str(exc))
+
+    if done:
+        _log("END", endpoint="/step", final_score=reward.value)
+
+    return StepResponse(
+        observation=obs,
+        reward=reward,
+        done=done,
+        info=info,
+    )
+
+
+@router.get(
+    "/state",
+    response_model=EnvironmentState,
+    summary="Return the full internal environment state",
+)
+async def state() -> EnvironmentState:
+    """Inspect the environment without mutating it."""
+    return _env.state()
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Liveness probe",
+)
+async def health() -> HealthResponse:
+    """Returns HTTP 200 with ``{"status": "ok"}``."""
+    return HealthResponse()

test_inference.py

@@ -0,0 +1,26 @@
+import sys
+sys.path.insert(0, ".")
+from inference import SYSTEM_PROMPT, TASK_IDS, _parse_json, _build_user_prompt
+from environment import Action
+
+print("Imports OK")
+print("Tasks:", TASK_IDS)
+
+# Test JSON parsing
+j = _parse_json('{"action_type": "submit_note", "soap_note": {"subjective": "S", "objective": "O", "assessment": "A", "plan": "P"}}')
+print("Parse OK:", j["action_type"])
+
+# Test markdown fence stripping
+fenced = '```json\n{"action_type": "submit_note", "soap_note": {"subjective": "S", "objective": "O", "assessment": "A", "plan": "P"}}\n```'
+j2 = _parse_json(fenced)
+print("Fence strip OK:", j2["action_type"])
+
+# Test Action creation from parsed output
+action = Action(**j2)
+print("Action created:", action.action_type, "/ sections:", list(action.soap_note.model_fields.keys()))
+
+# Test prompt building
+p = _build_user_prompt("Hello doctor", {"name": "Test", "age": 30})
+print("Prompt len:", len(p), "chars")
+
+print("\nAll checks passed.")

test_output.txt

@@ -0,0 +1,9 @@
+
+--- Sub-signal unit tests ---
+  [OK] conciseness(short): got=1.0  want=1.0
+  [OK] conciseness(long) : got=0.0  want=0.0
+  [OK] safe_lang(clean)  : got=1.0  want=1.0
+  [OK] safe_lang(unsafe) : got=0.0  want=0.0
+  [OK] format_valid(ok)  : got=1.0  want=1.0
+  [OK] format_valid(bad) : got=0.0  want=0.0
+  [OK] format_valid(clfy): got=1.0  want=1.0

test_reward.py

@@ -0,0 +1,75 @@
+import sys
+sys.path.insert(0, ".")
+
+from environment import ClinicalNoteScribeEnv, Action, SOAPNote
+from environment.reward import (
+    compute_reward, _conciseness_bonus, _safe_language_score, _format_valid,
+    WORD_LIMIT, FREE_STEPS, STEP_PENALTY_RATE, ERROR_PENALTY_RATE,
+)
+
+def check(label, got, want):
+    ok = abs(got - want) < 1e-6
+    sym = "OK" if ok else "FAIL"
+    print(f"  [{sym}] {label}: got={got}  want={want}")
+    return ok
+
+short_note = SOAPNote(
+    subjective="Headache and runny nose for 5 days.",
+    objective="BP 118/76, HR 72, afebrile, clear lungs.",
+    assessment="Viral URI.",
+    plan="DayQuil, fluids, rest. Follow up if fever develops.",
+)
+long_note  = SOAPNote(subjective=" ".join(["word"] * (WORD_LIMIT + 1)), objective="O", assessment="A", plan="P")
+unsafe_note = SOAPNote(subjective="Patient definitely has pneumonia.", objective="O", assessment="A", plan="P")
+empty_note  = SOAPNote(subjective="", objective="O", assessment="A", plan="P")
+
+submit_ok  = Action(action_type="submit_note", soap_note=short_note)
+submit_bad = Action(action_type="submit_note", soap_note=empty_note)
+clarify    = Action(action_type="request_clarify", clarify_question="fever?")
+
+print("\n--- Sub-signal unit tests ---")
+check("conciseness(short)", _conciseness_bonus(short_note), 1.0)
+check("conciseness(long) ", _conciseness_bonus(long_note),  0.0)
+check("safe_lang(clean)  ", _safe_language_score(short_note),  1.0)
+check("safe_lang(unsafe) ", _safe_language_score(unsafe_note), 0.0)
+check("format_valid(ok)  ", _format_valid(submit_ok),  1.0)
+check("format_valid(bad) ", _format_valid(submit_bad), 0.0)
+check("format_valid(clfy)", _format_valid(clarify),    1.0)
+
+print("\n--- grader=1.0, steps=2, errors=0 → expect value=1.0 ---")
+r = compute_reward(submit_ok, grader_score=1.0, step_count=2, errors_so_far=[])
+check("value            ", r.value, 1.0)
+check("grader_score wt  ", r.signals["grader_score"],         0.60)
+check("conciseness wt   ", r.signals["conciseness_bonus"],    0.10)
+check("safe_lang wt     ", r.signals["safe_language_score"],  0.15)
+check("format_valid wt  ", r.signals["format_valid"],         0.15)
+check("step_penalty     ", r.signals["step_penalty"],         0.0)
+check("error_penalty    ", r.signals["error_penalty"],        0.0)
+
+print("\n--- grader=1.0, steps=5 (+2 extra) → expect deduct 0.10 ---")
+r2 = compute_reward(submit_ok, grader_score=1.0, step_count=5, errors_so_far=[])
+check("step_penalty     ", r2.signals["step_penalty"], -(2 * STEP_PENALTY_RATE))
+check("value            ", r2.value, round(1.0 - 2 * STEP_PENALTY_RATE, 4))
+
+print("\n--- grader=1.0, steps=2, errors=2 → expect deduct 0.20 ---")
+r3 = compute_reward(submit_ok, grader_score=1.0, step_count=2, errors_so_far=["e1", "e2"])
+check("error_penalty    ", r3.signals["error_penalty"], -(2 * ERROR_PENALTY_RATE))
+check("value            ", r3.value, round(1.0 - 2 * ERROR_PENALTY_RATE, 4))
+
+print("\n--- all bad signals → expect value clamped to 0.0 ---")
+bad_note = SOAPNote(subjective=" ".join(["word"] * 500) + " Patient definitely has cancer.", objective="", assessment="A", plan="P")
+bad_act  = Action(action_type="submit_note", soap_note=bad_note)
+r4 = compute_reward(bad_act, grader_score=0.0, step_count=10, errors_so_far=["e1","e2","e3"])
+check("value clamped    ", r4.value, 0.0)
+
+print("\n--- end-to-end env: clarify(step1) then submit(step2) ---")
+env = ClinicalNoteScribeEnv()
+env.reset("easy_routine_checkup")
+_, rc, dc, _ = env.step(Action(action_type="request_clarify", clarify_question="did the patient report any fever?"))
+check("clarify done=False", float(dc), 0.0)
+_, rs, ds, _ = env.step(submit_ok)
+check("submit  done=True ", float(ds), 1.0)
+assert 0.0 <= rs.value <= 1.0
+print(f"  Final value: {rs.value}")
+print(f"  Signals: { {k:v for k,v in rs.signals.items() if not k.startswith('_')} }")
+print("\nAll done.")