Spaces:
Sleeping
Sleeping
File size: 9,659 Bytes
3863567 27697e4 3863567 27697e4 3863567 27697e4 3863567 27697e4 3863567 27697e4 3863567 27697e4 8410397 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 | """
Data models for the Medical Coding Auditor Environment.
The agent acts as a Medical Coding Auditor reviewing proposed ICD-10 and CPT codes
against clinical notes and patient demographics. It uses structured tools to query
coding guidelines, check NCCI edits, flag errors, and submit a final audit report.
"""
from typing import Any, Dict, List, Literal, Optional
from openenv.core.env_server.types import Action, Observation
from pydantic import ConfigDict, Field
# ---------------------------------------------------------------------------
# Action Space
# ---------------------------------------------------------------------------
class MedicalCodingAction(Action):
"""
A single action the auditor agent can take.
The agent selects one action_type per step and populates the relevant fields:
- query_guideline: Look up official ICD-10-CM or CPT coding guidelines for a code.
Required: code (str)
- check_ncci_edits: Check CMS NCCI PTP edit table for a pair of procedure codes.
Required: code1 (str), code2 (str)
- flag_error: Record a coding error in the draft audit report.
Required: code (str), error_type (str), justification (str)
error_type must be one of: demographic_mismatch, excludes1_conflict,
ncci_edit, specificity_error, untraceable_code
- ask_clarifying_question: Ask a simulated physician for missing clinical information.
Required: question (str)
Use when the clinical note is ambiguous or lacks information needed to
determine the correct code. The environment returns the physician's response.
- extract_evidence: Highlight a specific text span from the clinical note as evidence
supporting a coding decision. Grounds reasoning in documentation.
Required: evidence_text (str) — must be an exact substring of the clinical note.
- submit_audit: End the episode and submit the draft report for grading.
No additional fields required.
"""
model_config = ConfigDict(
extra="forbid",
validate_assignment=True,
)
action_type: Literal[
"query_guideline",
"check_ncci_edits",
"flag_error",
"ask_clarifying_question",
"extract_evidence",
"submit_audit",
] = Field(
...,
description=(
"Type of auditor action to execute. One of: "
"'query_guideline' (look up a code's official guidelines), "
"'check_ncci_edits' (check if two CPT codes have a PTP bundling conflict), "
"'flag_error' (record a coding error in the draft audit report), "
"'ask_clarifying_question' (ask physician for missing clinical information), "
"'submit_audit' (submit the completed audit report for grading)."
),
)
# -- query_guideline & flag_error fields --
code: Optional[str] = Field(
default=None,
description=(
"ICD-10-CM or CPT code to query or flag. "
"Required for action_type='query_guideline' and 'flag_error'."
),
)
# -- check_ncci_edits fields --
code1: Optional[str] = Field(
default=None,
description=(
"First CPT code to check in the NCCI edit table. "
"Required for action_type='check_ncci_edits'."
),
)
code2: Optional[str] = Field(
default=None,
description=(
"Second CPT code to check in the NCCI edit table. "
"Required for action_type='check_ncci_edits'."
),
)
# -- flag_error fields --
error_type: Optional[
Literal[
"demographic_mismatch",
"excludes1_conflict",
"ncci_edit",
"specificity_error",
"untraceable_code",
]
] = Field(
default=None,
description=(
"Classification of the coding error. "
"Required for action_type='flag_error'. "
"Options: 'demographic_mismatch' (code inapplicable to patient sex/age), "
"'excludes1_conflict' (two mutually exclusive diagnosis codes billed together), "
"'ncci_edit' (NCCI PTP bundling violation between procedure codes), "
"'specificity_error' (wrong 7th character or insufficient code specificity), "
"'untraceable_code' (code does not exist in any official code set)."
),
)
justification: Optional[str] = Field(
default=None,
description=(
"Clinical and coding rationale for the flagged error. "
"Required for action_type='flag_error'. "
"Should cite the specific guideline rule or NCCI edit that is violated."
),
)
# -- ask_clarifying_question fields --
question: Optional[str] = Field(
default=None,
description=(
"Question to ask the simulated physician for clarification. "
"Required for action_type='ask_clarifying_question'. "
"Use when documentation is ambiguous or missing information needed for coding."
),
)
# -- extract_evidence fields --
evidence_text: Optional[str] = Field(
default=None,
description=(
"Exact text span from the clinical note to extract as evidence. "
"Required for action_type='extract_evidence'. "
"Must be an exact substring of the clinical note. "
"Use to ground a coding decision in specific documentation."
),
)
# ---------------------------------------------------------------------------
# Observation Space
# ---------------------------------------------------------------------------
class MedicalCodingObservation(Observation):
"""
Observation returned by the environment after each step.
Contains the full case context (demographics, clinical note, proposed codes),
the agent's accumulating draft report, the result of the last tool call,
and the current reward/done signals.
"""
model_config = ConfigDict(
extra="forbid",
validate_assignment=True,
)
# -- Case context (constant across episode) --
task_id: str = Field(
default="",
description="Identifier of the current task (easy_demographic / medium_ncci_conflict / hard_specificity_untraceable).",
)
difficulty: str = Field(
default="",
description="Difficulty level: easy, medium, or hard.",
)
patient_demographics: Dict[str, Any] = Field(
default_factory=dict,
description=(
"Patient demographics: age (int), sex ('male'/'female'), "
"mrn (str), insurance (str)."
),
)
clinical_note: str = Field(
default="",
description="Unstructured clinical note describing the encounter and diagnoses.",
)
proposed_codes: Dict[str, Dict[str, str]] = Field(
default_factory=dict,
description=(
"Dictionary of proposed billing codes to validate. "
"Keys are code strings (e.g. 'E11.9', '93306'). "
"Values are dicts with 'description' (str) and 'code_type' ('ICD-10-CM' or 'CPT')."
),
)
# -- Dynamic state --
draft_report: List[Dict[str, Any]] = Field(
default_factory=list,
description=(
"Accumulating list of errors flagged so far. Each entry has: "
"code (str), error_type (str), justification (str), step (int)."
),
)
tool_result: str = Field(
default="",
description=(
"Textual result of the last action executed: "
"guideline text for query_guideline, "
"NCCI edit details for check_ncci_edits, "
"confirmation for flag_error, "
"grader score summary for submit_audit."
),
)
step_count: int = Field(
default=0,
description="Number of steps taken in the current episode.",
)
codes_queried: List[str] = Field(
default_factory=list,
description="List of codes already queried via query_guideline this episode (for loop detection).",
)
pairs_checked: List[str] = Field(
default_factory=list,
description="List of code pairs already checked via check_ncci_edits (formatted as 'code1|code2').",
)
clarifications_asked: List[str] = Field(
default_factory=list,
description="List of clarifying questions asked via ask_clarifying_question this episode.",
)
extracted_evidence: List[str] = Field(
default_factory=list,
description=(
"List of text spans extracted from the clinical note via extract_evidence this episode. "
"Each entry is an exact substring of the clinical note."
),
)
last_action_error: Optional[str] = Field(
default=None,
description="Error message if the last action was invalid (e.g. missing required field, hallucinated code), else null.",
)
grader_score: Optional[float] = Field(
default=None,
description="Final grader score [0.0, 1.0] set when submit_audit is called, else null.",
)
episode_metrics: Optional[Dict[str, Any]] = Field(
default=None,
description=(
"Detailed trajectory evaluation metrics, populated only when done=True. "
"Includes: trajectory_length, tool_failure_rate, investigation_coverage, "
"flag_precision, flag_recall, avg_reward_per_step, "
"investigation_before_flag_rate, clarification_count."
),
)
__all__ = ["MedicalCodingAction", "MedicalCodingObservation"]
|