Update README.md

README.md

@@ -79,6 +79,13 @@ openenv push
 
 ### Observation (MedObservation)
 
+### Clinical Case Input Format
+
+This JSON represents a single clinical case used as input (state) for the MedCodeRL environment.
+The agent uses this data to analyze the case and decide the correct medical coding or action.
+
+---
+
 | Field | Type | Description |
 |---|---|---|
 | `case_id` | str | Unique case identifier |
@@ -97,6 +104,139 @@ openenv push
 | `lab_results` | str/None | Lab findings |
 | `medications` | list[str] | Current medications |
 
+
+### 🧾 Example Input
+
+```json
+{
+  "case_id": "easy_123",
+  "difficulty": "easy",
+  "clinical_note": "Patient presents with severe sore throat...",
+  "symptoms": ["sore throat", "fever"],
+  "treatments": ["amoxicillin prescribing"],
+  "insurance_type": "Private",
+  "prior_auth_required": false,
+  "treatment_cost": "low",
+  "patient_age": 34,
+  "patient_sex": "F",
+  "provider_specialty": "Family Medicine",
+  "visit_type": "outpatient",
+  "comorbidities": [],
+  "medications": ["Ibuprofen"]
+}
+```
+
+---
+
+## 🔍 Field Descriptions
+
+### 🆔 `case_id`
+
+* Unique identifier for the clinical case
+* Helps track and reference specific cases
+
+---
+
+### 🎯 `difficulty`
+
+* Indicates complexity level of the case
+* Values: `easy`, `medium`, `hard`
+* Used for training and evaluation scaling
+
+---
+
+### 📝 `clinical_note`
+
+* Free-text description of the patient's condition
+* Contains detailed clinical information
+* **Most important field for decision-making**
+
+---
+
+### 🤒 `symptoms`
+
+* List of symptoms observed in the patient
+* Structured version of the clinical note
+* Helps simplify reasoning and rule-based checks
+
+---
+
+### 💊 `treatments`
+
+* Treatments or procedures performed by the provider
+* Used to validate correctness of medical actions
+
+---
+
+### 🏥 `insurance_type`
+
+* Type of patient insurance (e.g., Private, Government)
+* Affects billing rules and claim approvals
+
+---
+
+### 📄 `prior_auth_required`
+
+* Indicates if prior authorization is needed for treatment
+* `true` → approval required
+* `false` → no approval needed
+
+---
+
+### 💰 `treatment_cost`
+
+* Estimated cost category of treatment
+* Values: `low`, `medium`, `high`
+* Used in reward logic (penalizing unnecessary expensive treatments)
+
+---
+
+### 👤 `patient_age`
+
+* Age of the patient
+* Important for diagnosis and treatment decisions
+
+---
+
+### ⚧ `patient_sex`
+
+* Gender of the patient (`M` or `F`)
+* Required for gender-specific conditions
+
+---
+
+### 🩺 `provider_specialty`
+
+* Medical specialty of the healthcare provider
+* Example: `Family Medicine`, `Cardiology`
+* Used to validate if treatment is appropriate
+
+---
+
+### 🏥 `visit_type`
+
+* Type of medical visit
+* Values: `outpatient`, `inpatient`, `emergency`
+* Affects billing and coding rules
+
+---
+
+### 🤕 `comorbidities`
+
+* List of additional diseases or conditions
+* Example: diabetes, hypertension
+* Increases case complexity
+
+---
+
+### 💊 `medications`
+
+* Medications currently taken by the patient
+* Helps check for drug interactions and treatment safety
+
+
+
+
 ### Reward System
 
 **Grader Components (Deterministic, 0.0–1.0):**
@@ -110,7 +250,56 @@ openenv push
 | Risk flag identification | 5% |
 | Confidence calibration | 5% |
 
-**Shaped Penalties** (scaled by difficulty):
+## output example
+```json
+{
+    "diagnosis_codes": ["J02.9", "R50.9"],
+    "procedure_codes": ["99213"],
+    "decision": "approve",
+    "confidence": 0.85,
+    "reasoning": "Patient presented with acute pharyngitis and fever. E&M level 3 is appropriate for this outpatient visit. Medical necessity is documented.",
+    "modifier_codes": [],
+    "risk_flags": []
+}
+```
+
+#### How each field is useful (How the Grader Uses Them)
+there is a strict grading rubric that looks at the agent's output to calculate its final reward score. Here is exactly why each field is useful and how it literally affects the score:
+
+#### diagnosis_codes (Worth 35% of the grade)
+
+*Use*: These are the ICD-10 medical condition codes.
+*Impact*: The grader uses mathematical sets to compare the AI's codes with the hidden ground truth. If the AI misses the primary code or "undercodes," it is heavily penalized (e.g., -0.15 points).
+
+#### procedure_codes (Worth 20% of the grade)
+
+*Use*: These are the CPT billing codes for the work the doctor actually did.
+*Impact*: The grader compares these against the ground truth. If the AI hallucinates an extra, expensive procedure, it gets penalized for "upcoding" (a form of medical fraud).
+
+#### decision (Worth 25% of the grade)
+
+Use: The AI must choose to "approve", "reject", or "review" the billing claim based on whether the clinic notes legally justify the codes.
+Impact: This is very heavily weighted. If the AI chooses "reject" when it should be "approve" (wrong denial), it loses 20% of its score.
+#### reasoning (Worth 10% of the grade)
+
+Use: A short clinical justification explaining why the AI picked those codes.
+Impact: Your grader literally scans this text. It checks the length (longer explanations get more points) and specifically searches for medical keywords like "medically necessary", "guideline", "compliance", and "documentation". Missing these keywords lowers the grade.
+
+#### risk_flags (Worth 5% of the grade)
+
+Use: Identifying potential compliance violations like "upcoding_risk" or "bundling_violation".
+Impact: If the hidden answer key has risk flags and the AI successfully spots them, it gets a direct bonus multiplier. If it misses them, it loses out on that 5%.
+
+#### confidence (Worth 5% of the grade)
+
+Use: A number from 0.0 to 1.0 representing how sure the AI is about its answers.
+Impact: The grader tests for "confidence calibration." If the AI is 99% confident but gets all the codes completely wrong, it is penalized for being overconfident. If it's right but claims 10% confidence, it is penalized for being overly timid.
+
+#### modifier_codes
+
+Use: Special two-digit modifiers for complex billing scenarios. Included mainly for standardization, though they don't explicitly carry a separate mathematical weight in the current exact base grader.
+
+#### **Shaped Penalties** (scaled by difficulty):
 - Wrong approval: -0.25 | Wrong denial: -0.20
 - Upcoding: -0.15 | Missing primary code: -0.15
 - Undercoding: -0.10 | Unnecessary procedure: -0.10
@@ -198,10 +387,7 @@ my_env/
     └── requirements.txt      # Server dependencies
 ```
 
-## ⚠️ Disclaimer
+## Disclaimer
 
 This environment is a **simulation for AI training and evaluation only**. It does not use real patient data and should not be used for actual medical coding or billing. All clinical cases are synthetic.
 
-## License
-
-MIT License