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"]