Skip to content

synthetic

knowledge_graph.clinical.synthetic

Synthetic-100 note generation: local Qwen case cards from grouped MIMIC references, then two GPT-5.6-terra agent stages.

python -m knowledge_graph.clinical.synthetic cards      # 500 private references -> 100 Qwen case cards (local GPUs)
python -m knowledge_graph.clinical.synthetic expand     # case card -> fictional discharge note
python -m knowledge_graph.clinical.synthetic reformat   # note -> MIMIC-style blocks and sections

Only case cards and synthetic text reach the agents; source notes and their IDs stay in the local stage.

source_groups(out)

Sampled training-pool notes in groups of five; this private file never leaves the local stage.

Source code in src/knowledge_graph/clinical/synthetic.py
102
103
104
105
106
107
108
109
110
111
112
def source_groups(out):
    """Sampled training-pool notes in groups of five; this private file never leaves the local stage."""
    path = out / "private" / "source_groups.private.json"
    if path.exists():
        return json.loads(path.read_text(encoding="utf-8"))["groups"]
    ids = [line.strip() for line in POOL.read_text(encoding="utf-8").splitlines() if line.strip()]
    sampled = random.Random(SEED).sample(ids, SAMPLES)
    groups = [{"group_id": f"g{start // GROUP_SIZE:03d}", "source_note_ids": sampled[start:start + GROUP_SIZE]}
              for start in range(0, SAMPLES, GROUP_SIZE)]
    write_json(path, {"groups": groups})
    return groups

source_notes(ids)

Texts of the requested MIMIC notes, streamed from the two large note caches.

Source code in src/knowledge_graph/clinical/synthetic.py
115
116
117
118
119
120
121
122
123
124
125
def source_notes(ids):
    """Texts of the requested MIMIC notes, streamed from the two large note caches."""
    import ijson

    found = {}
    for cache in SOURCE_CACHES:
        with cache.open("rb") as handle:
            for note_id, note in ijson.kvitems(handle, "notes"):
                if note_id in ids:
                    found[note_id] = note
    return found

note_text(note)

Source code in src/knowledge_graph/clinical/synthetic.py
128
129
def note_text(note):
    return str(note.get("text") or "")

redact(source)

Mask bracketed placeholders and long numbers, and keep only the start and end of very long notes.

Source code in src/knowledge_graph/clinical/synthetic.py
132
133
134
135
136
137
138
def redact(source):
    """Mask bracketed placeholders and long numbers, and keep only the start and end of very long notes."""
    source = re.sub(r"\[\*\*.*?\*\*\]", "___", source, flags=re.DOTALL)
    source = re.sub(r"\b\d{6,}\b", "___", source)
    if len(source) <= 16_000:
        return source
    return source[:10_000] + "\n\n[LONG MIDDLE OMITTED FOR LOCAL STYLE INFERENCE]\n\n" + source[-6_000:]

target_words(source)

Word count clipped to 150-3,500 and rounded to a multiple of 50.

Source code in src/knowledge_graph/clinical/synthetic.py
141
142
143
def target_words(source):
    """Word count clipped to 150-3,500 and rounded to a multiple of 50."""
    return int(round(min(max(len(WORD.findall(source)), 150), 3_500) / 50.0) * 50)

card_prompt(group, notes)

Source code in src/knowledge_graph/clinical/synthetic.py
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
def card_prompt(group, notes):
    examples, targets = [], []
    for index, note_id in enumerate(group["source_note_ids"], start=1):
        targets.append(target_words(note_text(notes[note_id])))
        examples.append(f'<private_example index="{index}">\n{redact(note_text(notes[note_id]))}\n</private_example>')
    return f"""Create exactly one fictional case card inspired only by the aggregate
formatting and distribution of all five private examples below.

Mandatory novelty rules:
- Do not select, preserve, combine, or retell any individual source case.
- Use new broad diagnoses, comorbidity combinations, procedures, and course events.
- Avoid rare proper nouns and all exact numeric clinical values from the examples.
- Case cards must contain facts, not prose copied from a discharge note.
- The five reference lengths are {targets}; use their median, {int(statistics.median(targets))} words,
  as the single synthetic note's target length.
- Use this synthetic ID: syn-{group["group_id"]}.

Return one JSON object with key "cases" containing exactly one case. The case must contain:
synthetic_id, target_words, service, patient_profile (age_band and sex),
admission_scenario, primary_conditions, comorbidities, procedures,
course_events, discharge_medication_classes, follow_up,
section_plan (a list of heading, target_words, and style objects), and
format_features. Use arrays for all plural fields.

{chr(10).join(examples)}

/no_think"""

parse_card(raw, group, notes)

The single case of a Qwen answer, with its ID, group, and median reference length set by code.

Source code in src/knowledge_graph/clinical/synthetic.py
175
176
177
178
179
180
181
182
183
184
185
186
187
def parse_card(raw, group, notes):
    """The single case of a Qwen answer, with its ID, group, and median reference length set by code."""
    raw = raw.rsplit("</think>", 1)[-1].strip()
    if raw.startswith("```"):
        raw = re.sub(r"\s*```$", "", re.sub(r"^```(?:json|text)?\s*", "", raw)).strip()
    cases = json.loads(raw[raw.find("{"):raw.rfind("}") + 1])["cases"]
    case = cases[0]
    if len(cases) != 1 or any(field not in case for field in CARD_FIELDS):
        raise ValueError("expected exactly one case with every card field")
    case["synthetic_id"] = f"syn-{group['group_id']}"
    case["target_words"] = int(statistics.median(target_words(note_text(notes[i])) for i in group["source_note_ids"]))
    case["group_id"] = group["group_id"]
    return [case]

cards(args)

Source code in src/knowledge_graph/clinical/synthetic.py
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
def cards(args):
    out = args.out.resolve()
    path = out / "qwen_case_cards.jsonl"
    done = {row["group_id"]: row for row in read_jsonl(path)} if path.exists() else {}
    pending = [group for group in source_groups(out) if group["group_id"] not in done]
    if not pending:
        return 0
    from vllm import LLM, SamplingParams

    notes = source_notes({note_id for group in pending for note_id in group["source_note_ids"]})
    parallel = args.tensor_parallel_size
    llm = LLM(
        model=str(args.model),
        quantization="awq_marlin",
        tensor_parallel_size=parallel,
        gpu_memory_utilization=0.90,
        max_model_len=32_768,
        max_num_seqs=6,
        enable_prefix_caching=True,
        disable_custom_all_reduce=parallel > 1,
        enforce_eager=parallel > 1,
    )
    params = SamplingParams(temperature=0.55, top_p=0.9, max_tokens=3_000)
    total = len(done) + len(pending)
    chat = lambda batch: llm.chat(
        [
            [{"role": "system", "content": CARD_SYSTEM}, {"role": "user", "content": card_prompt(g, notes)}]
            for g in batch
        ],
        sampling_params=params,
    )
    for start in range(0, len(pending), 2):
        batch, rows = pending[start : start + 2], []
        for group, output in zip(batch, chat(batch)):
            for attempt in range(3):  # resample invalid JSON up to twice
                try:
                    case = parse_card(output.outputs[0].text, group, notes)
                    break
                except (json.JSONDecodeError, KeyError, IndexError, TypeError, ValueError):
                    if attempt == 2:
                        raise
                    output = chat([group])[0]
            rows.append({"group_id": group["group_id"], "cases": case})
        done.update({row["group_id"]: row for row in rows})
        write_jsonl(path, done.values())
        print(f"case cards: {len(done)}/{total} groups", flush=True)
    return 0

check_expansion(job)

One note with the requested synthetic ID and at least 80 words.

Source code in src/knowledge_graph/clinical/synthetic.py
242
243
244
245
246
247
248
249
250
251
def check_expansion(job):
    """One note with the requested synthetic ID and at least 80 words."""
    request, response = load_json(job / "input.json"), load_json(job / "response.json")
    notes = response.get("notes")
    if not isinstance(notes, list) or len(notes) != 1:
        return ["response must contain exactly one note"]
    expected, actual = [case["synthetic_id"] for case in request["cases"]], [note.get("synthetic_id") for note in notes]
    if actual != expected:
        return [f"synthetic IDs/order mismatch: {actual} != {expected}"]
    return [f"note too short: {note.get('synthetic_id')}" for note in notes if len(note_text(note).split()) < 80]

check_format(job)

Length, block and heading structure, plain text, and no dataset name; shorter notes are kept.

Source code in src/knowledge_graph/clinical/synthetic.py
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def check_format(job):
    """Length, block and heading structure, plain text, and no dataset name; shorter notes are kept."""
    request, response = load_json(job / "input.json"), load_json(job / "response.json")
    if response.get("synthetic_id") != request["synthetic_id"]:
        return ["synthetic_id mismatch"]
    note = note_text(response).strip()
    words, blocks, headings = len(WORD.findall(note)), len(BLOCK.split(note)), len(HEADING.findall(note))
    minimum = max(14, request["target_sections"] - 6)
    if words > request["maximum_words"]:
        return [
            f"word count {words}; require no more than {request['maximum_words']} around target {request['target_words']}"
        ]
    if abs(blocks - request["target_blocks"]) > 2:
        return [f"block count {blocks} not near target {request['target_blocks']}"]
    if headings < minimum:
        return [f"only {headings} headings; require {minimum}"]
    if MARKDOWN.search(note):
        return ["Markdown formatting remains"]
    if re.search(r"(?i)\bMIMIC(?:-III|-IV)?\b", note):
        return ["dataset name appears in note text"]
    return []

run_jobs(jobs, prompt, check, args, attempts, followup)

Run the agent on every job without a valid response, retrying generation and validation failures.

Source code in src/knowledge_graph/clinical/synthetic.py
277
278
279
280
281
282
283
284
285
286
287
288
def run_jobs(jobs, prompt, check, args, attempts, followup):
    """Run the agent on every job without a valid response, retrying generation and validation failures."""

    def errors(job):
        try:
            return check(job)
        except (json.JSONDecodeError, UnicodeDecodeError, FileNotFoundError) as error:  # missing or broken response
            return [str(error)]

    pending = [lambda s, job=job: agent(job, prompt, lambda _: errors(job), args, s, attempts=attempts, followup=followup)
               for job in jobs if errors(job)]
    return run(pending, args)

expand(args)

Source code in src/knowledge_graph/clinical/synthetic.py
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
def expand(args):
    out = args.out.resolve()
    card_rows = sorted(read_jsonl(out / "qwen_case_cards.jsonl"), key=lambda row: row["group_id"])
    schema = {
        "type": "object",
        "additionalProperties": False,
        "required": ["notes"],
        "properties": {"notes": {"type": "array", "minItems": 1, "maxItems": 1, "items": TEXT_SCHEMA}},
    }
    jobs = []
    for row in card_rows:
        job = out / "gpt_jobs" / row["group_id"]
        write_json(job / "input.json", {"group_id": row["group_id"], "cases": row["cases"]})
        write_json(job / "schema.json", schema)
        jobs.append(job)
    if run_jobs(jobs, EXPAND, check_expansion, args, 2, bullet_feedback("Correct every validation error:", 80)):
        return 1
    write_jsonl(out / "gpt_expanded.jsonl", [
        {"synthetic_id": note["synthetic_id"], "group_id": job.name, "text": note["text"].strip()}
        for job in sorted(jobs) for note in load_json(job / "response.json")["notes"]])
    return 0

reformat(args)

Source code in src/knowledge_graph/clinical/synthetic.py
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
def reformat(args):
    out = args.out.resolve()
    drafts = {row["group_id"]: row for row in read_jsonl(out / "gpt_expanded.jsonl")}
    card_rows = {row["group_id"]: row for row in read_jsonl(out / "qwen_case_cards.jsonl")}
    jobs = []
    for group_id in sorted(drafts):
        card = card_rows[group_id]["cases"][0]
        words = int(card["target_words"])
        job = out / "terra_format_jobs" / group_id
        write_json(job / "input.json", {
            "synthetic_id": drafts[group_id]["synthetic_id"],
            "target_words": words,
            "minimum_words": round(words * 0.85),
            "maximum_words": round(words * 1.15),
            "target_blocks": min(12, max(6, round(8.3 * words / 1540.7))),
            "target_sections": min(40, max(18, round(28.5 * words / 1540.7))),
            "case_card": card,
            "synthetic_draft": drafts[group_id]["text"],
        })
        write_json(job / "schema.json", TEXT_SCHEMA)
        jobs.append(job)
    followup = lambda feedback: (
        f"\n\nThe previous attempt failed mechanical validation: {feedback}. Correct this explicitly in the new response."
    )
    if run_jobs(jobs, REFORMAT, check_format, args, 3, followup):
        return 1
    write_jsonl(out / f"{FORMATTED}.jsonl", [
        {"synthetic_id": response["synthetic_id"], "text": response["text"].strip()}
        for response in (load_json(job / "response.json") for job in sorted(jobs))])
    return 0

main()

Source code in src/knowledge_graph/clinical/synthetic.py
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
def main():
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    stages = parser.add_subparsers(dest="stage", required=True)
    for name in ("cards", "expand", "reformat"):
        stage = stages.add_parser(name)
        stage.add_argument("--out", type=Path, default=OUT)
        if name == "cards":
            stage.add_argument("--model", default=str(QWEN), help="Local Qwen AWQ checkpoint")
            stage.add_argument("--tensor-parallel-size", type=int, default=2)
        else:
            stage.add_argument("--model", default="gpt-5.6-terra", help="Agent model")
            stage.add_argument("--reasoning-effort", default="high")
            stage.add_argument("--max-parallel", type=int, default=3)
    args = parser.parse_args()
    return {"cards": cards, "expand": expand, "reformat": reformat}[args.stage](args)