messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/generators/adt.py

@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate a corpus of conformant HL7 v2.5.1 **ADT** messages for testing.
+
+For every ADT trigger event defined in 2.5.1 (A01–A62, excluding the query event A19 and
+reserved A56–A59) this emits ``--count`` messages of fabricated-but-realistic data, one
+``.hl7`` file each, laid out under ``--out`` as ``<TRIGGER>/0001.hl7``. The reference-driven
+machinery lives in [_core.py](_core.py); this module supplies ADT's trigger→structure map,
+its own segment builders (MRG/NPU/DB1/IAM), and a two-block validation fallback.
+
+The 57 ADT trigger events share **25** message structures (e.g. A04/A08/A13 are all
+``ADT_A01``); hl7apy keys validation by structure, so MSH-9.3 is set to the structure id
+(CLAUDE.md §8). ``ADT_A17``/``ADT_A24``/``ADT_A37`` have two *ungrouped* PID blocks that
+hl7apy cannot validate whole, so each patient block is validated independently as an
+``ADT_A01`` superset (see :func:`_gate_two_block`). All data is synthetic — no real PHI.
+
+Usage::
+
+    python -m messagefoundry.generators.adt                 # all triggers, 50 each
+    python messagefoundry/generators/adt.py --triggers A01,A04 --count 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+from messagefoundry.parsing import HL7PeekError, Peek, normalize, validate
+from messagefoundry.generators import _core
+from messagefoundry.generators import _hl7data as d
+from messagefoundry.generators._core import Ctx, MessageSpec, next_seq, seg
+
+DEFAULT_SEED = _core.DEFAULT_SEED
+DEFAULT_OUT = "samples/messages/adt"
+
+# Trigger event -> 2.5.1 message structure (HL7 Chapter 3). Every value is one of hl7apy's
+# 25 ADT structures; shared triggers (e.g. A04->ADT_A01) carry the structure in MSH-9.3.
+TRIGGER_TO_STRUCTURE: dict[str, str] = {
+    "A01": "ADT_A01",
+    "A04": "ADT_A01",
+    "A08": "ADT_A01",
+    "A13": "ADT_A01",
+    "A02": "ADT_A02",
+    "A03": "ADT_A03",
+    "A05": "ADT_A05",
+    "A14": "ADT_A05",
+    "A28": "ADT_A05",
+    "A31": "ADT_A05",
+    "A06": "ADT_A06",
+    "A07": "ADT_A06",
+    "A09": "ADT_A09",
+    "A10": "ADT_A09",
+    "A11": "ADT_A09",
+    "A12": "ADT_A12",
+    "A15": "ADT_A15",
+    "A16": "ADT_A16",
+    "A17": "ADT_A17",
+    "A18": "ADT_A18",
+    "A20": "ADT_A20",
+    "A21": "ADT_A21",
+    "A22": "ADT_A21",
+    "A23": "ADT_A21",
+    "A25": "ADT_A21",
+    "A26": "ADT_A21",
+    "A27": "ADT_A21",
+    "A29": "ADT_A21",
+    "A32": "ADT_A21",
+    "A33": "ADT_A21",
+    "A24": "ADT_A24",
+    "A30": "ADT_A30",
+    "A34": "ADT_A30",
+    "A35": "ADT_A30",
+    "A36": "ADT_A30",
+    "A46": "ADT_A30",
+    "A47": "ADT_A30",
+    "A48": "ADT_A30",
+    "A49": "ADT_A30",
+    "A37": "ADT_A37",
+    "A38": "ADT_A38",
+    "A39": "ADT_A39",
+    "A40": "ADT_A39",
+    "A41": "ADT_A39",
+    "A42": "ADT_A39",
+    "A43": "ADT_A43",
+    "A44": "ADT_A43",
+    "A45": "ADT_A45",
+    "A50": "ADT_A50",
+    "A51": "ADT_A50",
+    "A52": "ADT_A52",
+    "A53": "ADT_A52",
+    "A54": "ADT_A54",
+    "A55": "ADT_A54",
+    "A60": "ADT_A60",
+    "A61": "ADT_A61",
+    "A62": "ADT_A61",
+}
+
+ALL_TRIGGERS: list[str] = sorted(TRIGGER_TO_STRUCTURE)
+
+# Optional segments we know how to build and will sprinkle in for realism where a structure
+# permits them. Required segments are always emitted regardless of this set.
+OPTIONAL_SEGMENT_ALLOWLIST: frozenset[str] = frozenset(
+    {"PD1", "PV1", "PV2", "NK1", "AL1", "DG1", "OBX", "DB1", "IAM"}
+)
+
+# Structures with two ungrouped PID blocks that hl7apy cannot validate as a whole.
+TWO_BLOCK_STRUCTURES: frozenset[str] = frozenset({"ADT_A17", "ADT_A24", "ADT_A37"})
+
+
+# --- ADT-specific segment builders -------------------------------------------
+
+
+def _build_mrg(rng: random.Random, ctx: Ctx) -> str:
+    return seg("MRG", {1: d.cx(str(rng.randint(1_000_000, 9_999_999)))})
+
+
+def _build_npu(rng: random.Random, ctx: Ctx) -> str:
+    status = rng.choice(d.BED_STATUSES)[0]
+    location = d.pl(
+        rng.choice(d.POINTS_OF_CARE),
+        rng.choice(d.ROOMS),
+        rng.choice(d.BEDS),
+        rng.choice(d.FACILITIES),
+    )
+    return seg("NPU", {1: location, 2: status})
+
+
+def _build_db1(rng: random.Random, ctx: Ctx) -> str:
+    return seg("DB1", {1: str(next_seq(ctx, "DB1")), 2: "PT"})
+
+
+def _build_iam(rng: random.Random, ctx: Ctx) -> str:
+    code, text = rng.choice(d.ALLERGENS)
+    sev_code, sev_text = rng.choice(d.ALLERGY_SEVERITIES)
+    return seg(
+        "IAM",
+        {
+            1: str(next_seq(ctx, "IAM")),
+            2: d.cwe("DA", "Drug allergy", "HL70127"),
+            3: d.cwe(code, text, "L"),
+            6: d.cwe(sev_code, sev_text, "HL70128"),
+        },
+    )
+
+
+_ADT_BUILDERS = {"MRG": _build_mrg, "NPU": _build_npu, "DB1": _build_db1, "IAM": _build_iam}
+
+
+# --- compliance gate (with the two-block fallback) ---------------------------
+
+
+def _gate(msg: str, structure: str) -> tuple[bool, list[str]]:
+    if structure in TWO_BLOCK_STRUCTURES:
+        return _gate_two_block(msg)
+    return _core.default_gate(msg, structure)
+
+
+def _gate_two_block(msg: str) -> tuple[bool, list[str]]:
+    """Validate each patient block of an A17/A24/A37 message independently.
+
+    hl7apy cannot validate two ungrouped PID blocks at once. Each block (PID + its encounter
+    segments) is a valid subset of ``ADT_A01``, so we wrap each as a minimal ADT_A01 and
+    validate that — proving field/segment conformance of both blocks.
+    """
+    try:
+        peek = Peek.parse(msg)
+    except HL7PeekError as exc:
+        return False, [f"peek parse error: {exc}"]
+
+    segment_ids = peek.segments()
+    pid_at = [i for i, s in enumerate(segment_ids) if s == "PID"]
+    if len(pid_at) != 2:
+        return False, [f"expected exactly 2 PID segments, found {len(pid_at)}"]
+
+    # normalize first: a message read back via Path.read_text has \r translated to \n.
+    lines = normalize(msg).strip("\r").split("\r")
+    blocks = (lines[pid_at[0] : pid_at[1]], lines[pid_at[1] :])
+    errors: list[str] = []
+    for n, block in enumerate(blocks, start=1):
+        wrapper = "\r".join(
+            [
+                r"MSH|^~\&|S|F|R|D|20260101000000||ADT^A08^ADT_A01|MEFORWRAP|P|2.5.1",
+                "EVN|A08|20260101000000",
+                *block,
+            ]
+        )
+        result = validate(wrapper, expected_version="2.5.1")
+        if not result.ok:
+            errors.extend(f"block{n}: {e}" for e in result.errors)
+    return (not errors), errors
+
+
+def _force(structure: str) -> frozenset[str]:
+    # Guarantee a PV1 in each two-block patient section so each validates as an ADT_A01.
+    return frozenset({"PV1"}) if structure in TWO_BLOCK_STRUCTURES else frozenset()
+
+
+_core.register(
+    MessageSpec(
+        code="ADT",
+        trigger_to_structure=TRIGGER_TO_STRUCTURE,
+        builders=_ADT_BUILDERS,
+        optional_allowlist=OPTIONAL_SEGMENT_ALLOWLIST,
+        force=_force,
+        gate=_gate,
+    )
+)
+
+
+# --- ADT-flavoured back-compat surface (used by tests / the CLI) -------------
+
+
+def generate_message(trigger: str, index: int, *, seed: str = DEFAULT_SEED) -> str:
+    """Build one ``\\r``-delimited ADT message for ``trigger`` (deterministic given seed)."""
+    return _core.generate_message("ADT", trigger, index, seed=seed)
+
+
+def gate(msg: str, structure: str) -> tuple[bool, list[str]]:
+    """Return ``(ok, errors)`` from strict hl7apy validation (with the two-block fallback)."""
+    return _core.gate("ADT", msg, structure)
+
+
+# --- CLI ---------------------------------------------------------------------
+
+
+def _parse_triggers(raw: str) -> list[str]:
+    if not raw:
+        return ALL_TRIGGERS
+    chosen = [t.strip().upper() for t in raw.split(",") if t.strip()]
+    unknown = [t for t in chosen if t not in TRIGGER_TO_STRUCTURE]
+    if unknown:
+        raise SystemExit(f"unknown ADT trigger(s): {', '.join(unknown)}")
+    return chosen
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Generate conformant HL7 v2.5.1 ADT messages.")
+    parser.add_argument("--out", default=DEFAULT_OUT, help=f"output root (default {DEFAULT_OUT})")
+    parser.add_argument("--count", type=int, default=50, help="messages per trigger (default 50)")
+    parser.add_argument("--triggers", default="", help="comma-separated subset (default: all)")
+    parser.add_argument("--seed", default=DEFAULT_SEED, help="RNG seed for reproducible output")
+    parser.add_argument("--quiet", action="store_true", help="suppress per-trigger progress")
+    parser.add_argument(
+        "--show-message",
+        action="store_true",
+        help="on validation failure, print the offending message to stderr (off by default)",
+    )
+    args = parser.parse_args(argv)
+
+    triggers = _parse_triggers(args.triggers)
+    out_root = Path(args.out)
+    total = 0
+
+    for trigger in triggers:
+        structure = TRIGGER_TO_STRUCTURE[trigger]
+        # Generate + strict-validate + write via the shared corpus writer: its cleanup is scoped
+        # to its own NNNN.hl7 files, never an arbitrary *.hl7 a user placed in the dir (low-19).
+        try:
+            result = _core.write_corpus(
+                "ADT", triggers=[trigger], count=args.count, out=args.out, seed=args.seed
+            )
+        except _core.GenerationError as exc:
+            print(f"VALIDATION FAILED: {trigger} #{exc.index} ({structure})", file=sys.stderr)
+            for err in exc.errors:
+                print(f"  - {err}", file=sys.stderr)
+            # Even though these are synthetic, don't dump a whole message to stderr by default —
+            # the pattern leaks if ever adapted to real data (docs/PHI.md §7). Opt in to debug.
+            if args.show_message:
+                print("--- offending message ---", file=sys.stderr)
+                print(exc.message.replace("\r", "\n"), file=sys.stderr)
+            else:
+                print("(re-run with --show-message to print it)", file=sys.stderr)
+            return 1
+        total += result.total
+        if not args.quiet:
+            print(f"{trigger} -> {structure}: {result.total} messages")
+
+    if not args.quiet:
+        print(f"\nGenerated {total} messages across {len(triggers)} triggers into {out_root}/")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

messagefoundry/generators/all_types.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Side-effect import that registers every built-in message type with the generator registry.
+
+Import this before reading ``_core.message_codes()`` (the harness GUI does). Each generator
+module registers itself on import; list new types here as they're built.
+"""
+
+from __future__ import annotations
+
+# Each import runs the module's _core.register(...) side effect.
+from messagefoundry.generators import adt  # noqa: F401
+from messagefoundry.generators import bar  # noqa: F401
+from messagefoundry.generators import dft  # noqa: F401
+from messagefoundry.generators import mdm  # noqa: F401
+from messagefoundry.generators import mfn  # noqa: F401
+from messagefoundry.generators import oml  # noqa: F401
+from messagefoundry.generators import orl  # noqa: F401
+from messagefoundry.generators import orm  # noqa: F401
+from messagefoundry.generators import oru  # noqa: F401
+from messagefoundry.generators import ras  # noqa: F401
+from messagefoundry.generators import rde  # noqa: F401
+from messagefoundry.generators import siu  # noqa: F401
+from messagefoundry.generators import vxu  # noqa: F401

messagefoundry/generators/bar.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **BAR** (add/change billing account) messages.
+
+BAR_Pxx require MSH + EVN + PID + a VISIT group; we add procedures (PR1), guarantor (GT1) and
+insurance (IN1) for realistic billing accounts.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import MessageSpec
+
+_core.register(
+    MessageSpec(
+        code="BAR",
+        # P10 omitted: requires GP1 (grouping/reimbursement), which we don't build.
+        trigger_to_structure={
+            "P01": "BAR_P01",
+            "P02": "BAR_P02",
+            "P05": "BAR_P05",
+            "P06": "BAR_P06",
+            "P12": "BAR_P12",
+        },
+        optional_allowlist=frozenset({"PV1", "PV2", "DG1", "GT1", "OBX", "AL1"}),
+        group_suffixes=frozenset({"_PROCEDURE", "_INSURANCE"}),
+    )
+)

messagefoundry/generators/dft.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **DFT** (detailed financial transaction) messages.
+
+DFT_P03/P11 require MSH + EVN + PID + a FINANCIAL group (→ FT1); we add an optional visit and
+diagnoses for realism.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import MessageSpec
+
+_core.register(
+    MessageSpec(
+        code="DFT",
+        trigger_to_structure={"P03": "DFT_P03", "P11": "DFT_P11"},
+        optional_allowlist=frozenset({"PV1", "PV2", "DG1"}),
+    )
+)

messagefoundry/generators/mdm.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **MDM** (medical document management) messages.
+
+MDM_T01/T02 require MSH + EVN + PID + PV1 + TXA (T02 adds an observation/OBX).
+"""
+
+from __future__ import annotations
+
+import random
+
+from messagefoundry.generators import _core
+from messagefoundry.generators import _hl7data as d
+from messagefoundry.generators._core import Ctx, MessageSpec, next_seq, seg
+
+
+def _build_txa(rng: random.Random, ctx: Ctx) -> str:
+    return seg(
+        "TXA",
+        {
+            1: str(next_seq(ctx, "TXA")),
+            2: rng.choice(d.DOCUMENT_TYPES),  # document type (required)
+            12: d.ei(
+                str(rng.randint(100_000, 999_999)), "DOC"
+            ),  # unique document number (required)
+            17: rng.choice(d.DOC_STATUSES),  # document completion status (required)
+        },
+    )
+
+
+_core.register(
+    MessageSpec(
+        code="MDM",
+        trigger_to_structure={"T01": "MDM_T01", "T02": "MDM_T02"},
+        builders={"TXA": _build_txa},
+        optional_allowlist=frozenset({"PD1", "PV2", "NK1", "OBX", "DG1", "AL1"}),
+        group_suffixes=frozenset({"_COMMON_ORDER", "_OBSERVATION"}),
+    )
+)

messagefoundry/generators/mfn.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **MFN** (master file notification) messages.
+
+We cover the generic master-file structures (M01, M13) that need only MFI + MFE. The typed
+variants (M02→STF, M04→CDM, M05→LOC/LDP, …) require master-file-specific segments we don't build.
+"""
+
+from __future__ import annotations
+
+import random
+
+from messagefoundry.generators import _core
+from messagefoundry.generators import _hl7data as d
+from messagefoundry.generators._core import Ctx, MessageSpec, seg
+
+
+def _build_mfi(rng: random.Random, ctx: Ctx) -> str:
+    return seg(
+        "MFI",
+        {
+            1: d.cwe("PRA", "Practitioner master file", "HL70175"),  # master file id (required)
+            3: "REP",  # file-level event code (required)
+            6: "NE",  # response level code (required)
+        },
+    )
+
+
+def _build_mfe(rng: random.Random, ctx: Ctx) -> str:
+    return seg(
+        "MFE",
+        {
+            1: rng.choice(("MAD", "MUP", "MDC")),  # record-level event code (required)
+            4: d.cwe(f"KEY{rng.randint(100, 999)}", "Master record", "L"),  # primary key (required)
+            5: "CWE",  # primary key value type (required)
+        },
+    )
+
+
+_core.register(
+    MessageSpec(
+        code="MFN",
+        trigger_to_structure={"M01": "MFN_M01", "M13": "MFN_M13"},
+        builders={"MFI": _build_mfi, "MFE": _build_mfe},
+    )
+)

messagefoundry/generators/oml.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **OML** (laboratory order) messages — the modern,
+cleanly-structured successor to ORM for OBR-based orders, with specimen (SPM) support.
+"""
+
+from __future__ import annotations
+
+import random
+
+from messagefoundry.generators import _core
+from messagefoundry.generators import _hl7data as d
+from messagefoundry.generators._core import Ctx, MessageSpec, next_seq, seg
+
+
+def _build_spm(rng: random.Random, ctx: Ctx) -> str:
+    code, text = rng.choice(d.SPECIMEN_TYPES)
+    return seg("SPM", {1: str(next_seq(ctx, "SPM")), 4: d.cwe(code, text, "HL70487")})
+
+
+_core.register(
+    MessageSpec(
+        code="OML",
+        # O35 omitted: requires SAC (specimen container), which we don't build.
+        trigger_to_structure={"O21": "OML_O21", "O33": "OML_O33"},
+        builders={"SPM": _build_spm},
+        optional_allowlist=frozenset({"PD1", "PV2", "DG1", "OBX"}),
+        group_suffixes=frozenset(
+            {"_PATIENT", "_PATIENT_VISIT", "_OBSERVATION_REQUEST", "_OBSERVATION", "_SPECIMEN"}
+        ),
+    )
+)

messagefoundry/generators/orl.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **ORL** (laboratory order response) messages.
+
+ORL is an order acknowledgement: MSH + MSA, optionally echoing the patient/order. We emit an
+AA acknowledgement plus the optional response patient block.
+"""
+
+from __future__ import annotations
+
+import random
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import Ctx, MessageSpec, seg
+
+
+def _build_msa(rng: random.Random, ctx: Ctx) -> str:
+    # MSA-1 acknowledgement code, MSA-2 the (fabricated) control id being acknowledged.
+    return seg("MSA", {1: "AA", 2: f"REQ{rng.randint(10_000, 99_999)}"})
+
+
+# ORL is an acknowledgement: MSH + MSA is conformant for every ORL structure. We don't echo the
+# patient/order block — O34/O36 nest a required SPM-bearing order group we don't populate.
+_core.register(
+    MessageSpec(
+        code="ORL",
+        trigger_to_structure={"O22": "ORL_O22", "O34": "ORL_O34", "O36": "ORL_O36"},
+        builders={"MSA": _build_msa},
+    )
+)

messagefoundry/generators/orm.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **ORM** (general order) messages.
+
+ORM_O01 only *requires* MSH + ORC; we include the optional PATIENT group (PID/PV1) for realism.
+We deliberately omit ORDER_DETAIL: hl7apy models its OBR/RQD/RQ1/RXO/ODS/ODT subgroup as
+all-required rather than a choice, so it can't be populated sensibly — OBR-based orders are
+better expressed via OML (the modern lab order) instead.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import MessageSpec
+
+_core.register(
+    MessageSpec(
+        code="ORM",
+        trigger_to_structure={"O01": "ORM_O01"},
+        optional_allowlist=frozenset({"PD1", "PV2"}),
+        group_suffixes=frozenset({"_PATIENT", "_PATIENT_VISIT"}),
+    )
+)

messagefoundry/generators/oru.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **ORU** (observation result) messages.
+
+The required PATIENT_RESULT → ORDER_OBSERVATION groups give MSH + OBR; we include the optional
+PATIENT (PID) and OBSERVATION (OBX) groups so results carry a patient and values.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import MessageSpec
+
+_core.register(
+    MessageSpec(
+        code="ORU",
+        trigger_to_structure={"R01": "ORU_R01", "R30": "ORU_R30"},
+        optional_allowlist=frozenset({"ORC", "PD1", "NK1"}),
+        group_suffixes=frozenset({"_PATIENT", "_OBSERVATION"}),
+    )
+)

messagefoundry/generators/ras.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **RAS** (pharmacy/treatment administration) messages.
+
+The required ADMINISTRATION group carries RXA; ORC/RXA/RXR are shared builders.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.generators import _core
+from messagefoundry.generators._core import MessageSpec
+
+_core.register(
+    MessageSpec(
+        code="RAS",
+        trigger_to_structure={"O17": "RAS_O17"},
+        optional_allowlist=frozenset({"PD1", "PV2", "AL1", "RXR"}),
+        group_suffixes=frozenset({"_PATIENT", "_PATIENT_VISIT"}),
+    )
+)

messagefoundry/generators/rde.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Generate conformant HL7 v2.5.1 **RDE** (pharmacy/treatment encoded order) messages.
+
+hl7apy's parser greedily assigns a TQ1 to the optional ``RDE_O11_TIMING`` group (which precedes
+RXE) and never to the *required* ``RDE_O11_TIMING_ENCODED`` group — so it false-flags
+TIMING_ENCODED as missing even though the message carries a TQ1 in the right place. We emit the
+correct segments (ORC/RXE/TQ1/RXR) and a narrow gate tolerates that one tool-limitation error
+(a spec-correct message), failing on anything else. (Same spirit as ADT's two-block fallback.)
+"""
+
+from __future__ import annotations
+
+import random
+
+from messagefoundry.parsing import validate
+from messagefoundry.generators import _core
+from messagefoundry.generators import _hl7data as d
+from messagefoundry.generators._core import Ctx, MessageSpec, next_seq, seg
+
+
+def _build_rxe(rng: random.Random, ctx: Ctx) -> str:
+    code, text = rng.choice(d.MEDICATIONS)
+    return seg(
+        "RXE",
+        {
+            2: d.cwe(code, text, "RxNorm"),  # give code (required)
+            3: "1",  # give amount minimum (required)
+            5: d.cwe("mg", "milligram", "UCUM"),  # give units (required)
+        },
+    )
+
+
+def _build_tq1(rng: random.Random, ctx: Ctx) -> str:
+    return seg("TQ1", {1: str(next_seq(ctx, "TQ1"))})
+
+
+def _gate(msg: str, structure: str) -> tuple[bool, list[str]]:
+    result = validate(msg, expected_version="2.5.1")
+    # Tolerate only the known TIMING_ENCODED mis-grouping; any other error is a real failure.
+    remaining = [e for e in result.errors if "TIMING_ENCODED" not in e]
+    return (not remaining), remaining
+
+
+_core.register(
+    MessageSpec(
+        code="RDE",
+        trigger_to_structure={"O11": "RDE_O11"},
+        builders={"RXE": _build_rxe, "TQ1": _build_tq1},
+        optional_allowlist=frozenset({"PD1", "PV2"}),
+        group_suffixes=frozenset({"_PATIENT", "_PATIENT_VISIT"}),
+        gate=_gate,
+    )
+)