File size: 16,332 Bytes
8667e08
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
"""
Randomized Case Generator for the Medical Coding Auditor Environment.

Generates procedurally-created task scenarios by composing error templates
from the existing guideline data. Each generated case is deterministic given
the same seed (derived from episode_id), so grading remains reproducible.

Supports difficulty targeting: random_easy, random_medium, random_hard, random_expert,
or plain "random" for a random difficulty.
"""

from __future__ import annotations

import hashlib
import random
from typing import Any, Dict, List, Optional, Tuple

# ---------------------------------------------------------------------------
# Patient templates
# ---------------------------------------------------------------------------

_FIRST_NAMES_M = ["James", "Robert", "Michael", "David", "William", "Thomas", "Richard", "Charles"]
_FIRST_NAMES_F = ["Mary", "Patricia", "Jennifer", "Linda", "Elizabeth", "Susan", "Karen", "Nancy"]
_LAST_INITIALS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
_INSURANCES = [
    "Blue Cross PPO", "Medicare Part B", "Aetna HMO",
    "United Healthcare PPO", "Cigna EPO", "Humana Gold Plus",
    "Anthem Blue Shield", "Tricare Standard",
]


def _make_patient(rng: random.Random, sex: Optional[str] = None) -> Dict[str, Any]:
    """Generate a random patient with demographics."""
    if sex is None:
        sex = rng.choice(["male", "female"])
    age = rng.randint(22, 78)
    first = rng.choice(_FIRST_NAMES_M if sex == "male" else _FIRST_NAMES_F)
    last_init = rng.choice(_LAST_INITIALS)
    return {
        "age": age,
        "sex": sex,
        "mrn": f"MRN-GEN-{rng.randint(1000, 9999)}",
        "insurance": rng.choice(_INSURANCES),
        "_name": f"{first} {last_init}.",
    }


# ---------------------------------------------------------------------------
# Error templates β€” each returns (proposed_codes_fragment, expected_error, note_snippet)
# ---------------------------------------------------------------------------

def _error_demographic_mismatch(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """O80 on a male patient."""
    patient["sex"] = "male"  # force male for this error
    codes = {
        "O80": {"description": "Encounter for full-term uncomplicated delivery", "code_type": "ICD-10-CM"},
    }
    error = {
        "code": "O80",
        "error_type": "demographic_mismatch",
        "description": "O80 is a maternity code applicable only to female patients. Cannot be assigned to a male patient.",
        "key_terms": ["female", "male", "maternity", "obstetric", "delivery", "sex", "gender", "demographic"],
    }
    title = "Mr." if patient["sex"] == "male" else "Ms."
    note = (
        f"HISTORY OF PRESENT ILLNESS: {title} {patient['_name']} is a "
        f"{patient['age']}-year-old {patient['sex']} presenting for a routine wellness visit. "
        f"No obstetric or gynecological history is documented."
    )
    return codes, error, note


def _error_excludes1_copd_asthma(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """J44.1 + J45.20 Excludes1 conflict."""
    codes = {
        "J44.1": {"description": "COPD with acute exacerbation", "code_type": "ICD-10-CM"},
        "J45.20": {"description": "Mild intermittent asthma, uncomplicated", "code_type": "ICD-10-CM"},
    }
    error = {
        "code": "J44.1",
        "error_type": "excludes1_conflict",
        "conflicting_code": "J45.20",
        "description": "J44.1 (COPD) has Excludes1 for J45 (asthma). Mutually exclusive β€” cannot code together.",
        "key_terms": ["Excludes1", "mutually exclusive", "asthma", "COPD", "J45", "J44", "cannot be coded together"],
    }
    note = (
        f"HISTORY OF PRESENT ILLNESS: Patient has a 15-year history of COPD (GOLD stage II). "
        f"Presenting with acute exacerbation β€” increased dyspnea and sputum. "
        f"Prior asthma label from primary care was superseded by COPD diagnosis after PFTs "
        f"confirmed irreversible obstruction. Patient does NOT carry a concurrent asthma diagnosis.\n\n"
        f"SPIROMETRY: FEV1 48% predicted, post-bronchodilator improvement <10% (consistent with COPD)."
    )
    return codes, error, note


def _error_excludes1_diabetes(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """E10.9 + E11.9 Excludes1 conflict."""
    codes = {
        "E10.9": {"description": "Type 1 diabetes mellitus without complications", "code_type": "ICD-10-CM"},
        "E11.9": {"description": "Type 2 diabetes mellitus without complications", "code_type": "ICD-10-CM"},
    }
    error = {
        "code": "E10.9",
        "error_type": "excludes1_conflict",
        "conflicting_code": "E11.9",
        "description": "E10.9 (Type 1 DM) has Excludes1 for E11 (Type 2 DM). Mutually exclusive.",
        "key_terms": ["Excludes1", "mutually exclusive", "Type 1", "Type 2", "E11", "E10", "diabetes"],
    }
    note = (
        f"ENDOCRINOLOGY ASSESSMENT: Patient has Type 2 diabetes mellitus, managed with metformin. "
        f"C-peptide is normal (2.3 ng/mL), GAD65 autoantibodies are negative, "
        f"ruling out autoimmune Type 1 diabetes. Diagnosis is definitively Type 2 only."
    )
    return codes, error, note


def _error_ncci_echo(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """93306 + 93307 or 93306 + 93308 NCCI bundling."""
    limited = rng.choice(["93307", "93308"])
    limited_desc = (
        "Echocardiography, transthoracic, limited study without Doppler"
        if limited == "93307"
        else "Echocardiography, transthoracic, follow-up or limited study"
    )
    codes = {
        "93306": {"description": "Echocardiography, transthoracic, complete with Doppler", "code_type": "CPT"},
        limited: {"description": limited_desc, "code_type": "CPT"},
    }
    error = {
        "code": "93306",
        "error_type": "ncci_edit",
        "conflicting_code": limited,
        "description": f"93306 (complete TTE) and {limited} (limited TTE) are NCCI PTP edit β€” unbundling violation.",
        "key_terms": ["bundling", "unbundling", "NCCI", "PTP", "complete", "limited", limited, "comprehensive"],
    }
    note = (
        f"SERVICES RENDERED: A complete transthoracic echocardiogram was performed with 2D imaging, "
        f"M-mode, spectral Doppler, and color flow Doppler. LVEF estimated at {rng.randint(40, 60)}%. "
        f"Additionally, a limited echocardiographic study was documented for focused wall motion assessment."
    )
    return codes, error, note


def _error_ncci_em(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """99213 + 99214 E/M unbundling."""
    codes = {
        "99213": {"description": "Office visit, low-moderate complexity", "code_type": "CPT"},
        "99214": {"description": "Office visit, moderate-high complexity", "code_type": "CPT"},
    }
    error = {
        "code": "99213",
        "error_type": "ncci_edit",
        "conflicting_code": "99214",
        "description": "99213 and 99214 are different E/M levels for the same service β€” NCCI edit, only one should be billed.",
        "key_terms": ["bundling", "NCCI", "E/M", "99213", "99214", "same service", "unbundling"],
    }
    note = (
        f"SERVICES RENDERED: An office visit was performed. Medical decision making was "
        f"moderate to high complexity given the patient's multiple chronic conditions."
    )
    return codes, error, note


def _error_specificity_fracture(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """S52.501A wrong 7th character (should be D for follow-up)."""
    codes = {
        "S52.501A": {
            "description": "Fracture of lower end of right radius, initial encounter",
            "code_type": "ICD-10-CM",
        },
    }
    error = {
        "code": "S52.501A",
        "error_type": "specificity_error",
        "description": "7th character 'A' (initial) is wrong β€” this is a follow-up visit. Should be S52.501D (subsequent).",
        "key_terms": ["7th character", "subsequent", "initial", "follow-up", "healing", "S52.501D", "phase of care"],
    }
    weeks = rng.randint(4, 12)
    note = (
        f"HISTORY OF PRESENT ILLNESS: Patient presents for follow-up {weeks} weeks after closed "
        f"fracture of distal right radius. Cast was removed previously. X-ray shows routine healing "
        f"with appropriate callus formation.\n\n"
        f"Note: This is a SUBSEQUENT ENCOUNTER for a healing fracture β€” active treatment concluded {weeks} weeks ago."
    )
    return codes, error, note


def _error_untraceable_code(
    rng: random.Random, patient: Dict[str, Any], data: Dict[str, Any],
) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Any], str]:
    """A fabricated ICD-10 code that doesn't exist."""
    fake_codes = ["Z99.999", "E99.99", "J99.999", "M99.999", "R99.999"]
    fake = rng.choice(fake_codes)
    codes = {
        fake: {"description": "Unspecified condition (placeholder)", "code_type": "ICD-10-CM"},
    }
    error = {
        "code": fake,
        "error_type": "untraceable_code",
        "description": f"{fake} does not exist in the official ICD-10-CM tabular list. Untraceable code.",
        "key_terms": ["invalid", "untraceable", "not exist", "not found", "official", "billable"],
    }
    note = ""  # untraceable codes don't need clinical note context
    return codes, error, note


# ---------------------------------------------------------------------------
# Filler codes (valid, no errors β€” false positive traps)
# ---------------------------------------------------------------------------

_FILLER_CODES: List[Dict[str, Any]] = [
    {"code": "Z00.00", "description": "Encounter for general adult medical examination", "code_type": "ICD-10-CM"},
    {"code": "Z87.891", "description": "Personal history of other specified conditions", "code_type": "ICD-10-CM"},
    {"code": "M79.621", "description": "Pain in right upper arm", "code_type": "ICD-10-CM"},
    {"code": "99213", "description": "Office visit, low-moderate complexity", "code_type": "CPT"},
    {"code": "99214", "description": "Office visit, moderate-high complexity", "code_type": "CPT"},
]


# ---------------------------------------------------------------------------
# Error pools per difficulty
# ---------------------------------------------------------------------------

_ERROR_POOL_EASY = [_error_demographic_mismatch]
_ERROR_POOL_MEDIUM = [_error_excludes1_copd_asthma, _error_excludes1_diabetes, _error_ncci_echo, _error_ncci_em]
_ERROR_POOL_HARD = [_error_specificity_fracture, _error_untraceable_code]

_DIFFICULTY_CONFIG = {
    "easy":   {"error_count": 1, "pools": [_ERROR_POOL_EASY], "filler_count": (1, 2), "max_steps": 10},
    "medium": {"error_count": 1, "pools": [_ERROR_POOL_MEDIUM], "filler_count": (1, 2), "max_steps": 15},
    "hard":   {"error_count": 2, "pools": [_ERROR_POOL_MEDIUM, _ERROR_POOL_HARD], "filler_count": (1, 2), "max_steps": 20},
    "expert": {"error_count": 3, "pools": [_ERROR_POOL_EASY, _ERROR_POOL_MEDIUM, _ERROR_POOL_HARD], "filler_count": (1, 3), "max_steps": 25},
}


# ---------------------------------------------------------------------------
# Clinical note assembly
# ---------------------------------------------------------------------------

def _assemble_clinical_note(
    patient: Dict[str, Any],
    error_snippets: List[str],
    rng: random.Random,
) -> str:
    """Compose a synthetic clinical note from patient info and error-specific snippets."""
    title = "Mr." if patient["sex"] == "male" else "Ms."
    age = patient["age"]
    sex = patient["sex"]

    parts = [
        f"REASON FOR VISIT: Comprehensive evaluation and management.",
        "",
    ]

    # Add error-specific clinical content
    for snippet in error_snippets:
        if snippet:
            parts.append(snippet)
            parts.append("")

    # Generic physical exam
    bp_sys = rng.randint(110, 150)
    bp_dia = rng.randint(70, 95)
    hr = rng.randint(62, 98)
    parts.extend([
        f"PHYSICAL EXAM: Vitals: BP {bp_sys}/{bp_dia}, HR {hr}. "
        f"General: {title} {patient['_name']} is a {age}-year-old {sex} "
        f"in no acute distress. Exam otherwise unremarkable for areas not addressed above.",
        "",
        f"ASSESSMENT AND PLAN: See individual assessments above. "
        f"Return for follow-up as indicated.",
    ])

    return "\n".join(parts)


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------

def generate_random_task(
    data: Dict[str, Any],
    seed: str,
    difficulty: Optional[str] = None,
) -> Dict[str, Any]:
    """
    Generate a random task scenario.

    Args:
        data: The loaded ground_truth_cases.json data (for guideline reference).
        seed: A string seed for deterministic generation (typically episode_id).
        difficulty: One of 'easy', 'medium', 'hard', 'expert', or None (random).

    Returns:
        A task dict in the same format as the fixed tasks in ground_truth_cases.json.
    """
    # Deterministic RNG from seed
    seed_int = int(hashlib.sha256(seed.encode()).hexdigest()[:16], 16)
    rng = random.Random(seed_int)

    # Pick difficulty
    if difficulty not in _DIFFICULTY_CONFIG:
        difficulty = rng.choice(list(_DIFFICULTY_CONFIG.keys()))
    config = _DIFFICULTY_CONFIG[difficulty]

    # Generate patient
    patient = _make_patient(rng)

    # Select error generators β€” pick one from each pool, up to error_count
    error_generators = []
    pools = list(config["pools"])
    for _ in range(config["error_count"]):
        if not pools:
            break
        pool = pools.pop(0)
        gen = rng.choice(pool)
        error_generators.append(gen)

    # Generate errors
    proposed_codes: Dict[str, Dict[str, str]] = {}
    expected_errors: List[Dict[str, Any]] = []
    note_snippets: List[str] = []
    used_codes: set = set()

    for gen_fn in error_generators:
        codes_frag, error, snippet = gen_fn(rng, patient, data)
        # Avoid code collisions
        if any(c in used_codes for c in codes_frag):
            continue
        proposed_codes.update(codes_frag)
        used_codes.update(codes_frag.keys())
        expected_errors.append(error)
        note_snippets.append(snippet)

    # Add filler codes (false-positive traps)
    filler_min, filler_max = config["filler_count"]
    n_fillers = rng.randint(filler_min, filler_max)
    available_fillers = [f for f in _FILLER_CODES if f["code"] not in used_codes]
    rng.shuffle(available_fillers)
    for filler in available_fillers[:n_fillers]:
        proposed_codes[filler["code"]] = {
            "description": filler["description"],
            "code_type": filler["code_type"],
        }

    # Assemble clinical note
    clinical_note = _assemble_clinical_note(patient, note_snippets, rng)

    # Build hints
    hints = [
        "This is a procedurally generated case β€” investigate all proposed codes systematically.",
        f"Expect approximately {len(expected_errors)} error(s) in this case.",
        "Not every code has an error β€” avoid false positives.",
    ]

    # Remove _name from patient before returning (internal only)
    patient_clean = {k: v for k, v in patient.items() if not k.startswith("_")}

    return {
        "task_id": f"random_{difficulty}_{seed[:8]}",
        "difficulty": difficulty,
        "description": f"Procedurally generated {difficulty} case with {len(expected_errors)} error(s).",
        "scenario": f"A {patient['age']}-year-old {patient['sex']} patient encounter with {len(proposed_codes)} proposed codes.",
        "patient": patient_clean,
        "clinical_note": clinical_note,
        "proposed_codes": proposed_codes,
        "expected_errors": expected_errors,
        "max_steps": config["max_steps"],
        "hints": hints,
    }