lgd-engine 0.1.0__py3-none-any.whl

lgd_engine/__init__.py

@@ -0,0 +1,9 @@
+"""lgd-engine: LGD (有籍有证有门禁) minimal kernel.
+
+Version: 0.1.0
+Domain-agnostic gate + memory + judge skeleton, with the 510(k) change
+classification judge as the first concrete domain adapter.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

lgd_engine/cli.py

@@ -0,0 +1,116 @@
+"""lgd_engine.cli — console entry point (pyproject: lgd-gate = lgd_engine.cli:main).
+
+Thin CLI over the judgment core. Mirrors demo1.change_gate without depending on
+the demo layer; exit codes follow the release-gate convention:
+  0=go, 1=hold, 2=reject, 3=tool error, 64=usage error.
+
+`--all DIR` exists because the docs showed `--all` on this entry and it was only
+implemented on the demo CLI — a documented command that errored out is a defect
+in the doc surface, so the parity is now real (R19).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .gate import GateEngine
+from .judges.judge_510k import Judge510kChange
+from .judges.judge_postmarket import JudgePostmarket
+
+_DOMAINS = {
+    "510k": Judge510kChange,
+    "postmarket": JudgePostmarket,
+}
+_STRIP_KEYS = ("expected_verdict", "expected_fda_verdict",
+               "expected_nmpa_verdict", "_desensitized_from")
+RC_USAGE, RC_TOOL_ERROR = 64, 3
+_RC = {"go": 0, "hold": 1, "reject": 2}
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:      # argparse exits 2 by default
+        self.print_usage(sys.stderr)
+        print(f"{self.prog}: error: {message}", file=sys.stderr)
+        print(f"(usage errors exit {RC_USAGE}, not 2 — 2 means REJECT)", file=sys.stderr)
+        raise SystemExit(RC_USAGE)
+
+
+def _run_one(path: Path, args) -> tuple:
+    ctx = json.loads(path.read_text(encoding="utf-8"))
+    expected = ctx.get("expected_verdict")
+    for k in _STRIP_KEYS:
+        ctx.pop(k, None)
+    if args.jurisdiction:
+        ctx["jurisdiction"] = args.jurisdiction
+    eng = GateEngine()
+    eng.register(_DOMAINS[args.domain]())
+    return eng.evaluate(ctx), expected
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = _Parser(
+        prog="lgd-gate",
+        description="LGD Engine judgment core — go / hold / reject from a change context.",
+    )
+    ap.add_argument("--case", type=str,
+                    help="path to a case JSON (change context; expected_* keys are stripped)")
+    ap.add_argument("--all", metavar="CASES_DIR",
+                    help="run every *.json case in this directory")
+    ap.add_argument("--domain", choices=list(_DOMAINS), default="510k",
+                    help="judge family to run (default 510k)")
+    ap.add_argument("--jurisdiction", choices=["FDA", "NMPA"], default=None,
+                    help="override the jurisdiction in the case JSON")
+    args = ap.parse_args(argv)
+
+    if bool(args.case) == bool(args.all):
+        ap.error("exactly one of --case PATH or --all CASES_DIR is required")
+
+    if args.all:
+        root = Path(args.all)
+        if not root.is_dir():
+            ap.error(f"--all expects a directory, got {root}")
+        cases = sorted(root.glob("*.json"))
+        if not cases:
+            ap.error(f"no *.json cases under {root}")
+        matched = 0
+        for c in cases:
+            try:
+                report, expected = _run_one(c, args)
+            except Exception as exc:
+                print(f"[ENGINE ERROR] {c.name}: {type(exc).__name__}: {exc}", file=sys.stderr)
+                print(f"             exit {RC_TOOL_ERROR} = the tool failed; this is not "
+                      f"a verdict.", file=sys.stderr)
+                return RC_TOOL_ERROR
+            got = report.verdict
+            if expected and got == expected:
+                matched += 1
+            print(f"{c.name}: {got}"
+                  + (f" (expected {expected})" if expected else ""))
+        print(f"\n[summary] {matched}/{len(cases)} cases match expected verdict "
+              f"(domain={args.domain})")
+        return 0 if matched == len(cases) else 1
+
+    path = Path(args.case)
+    if not path.is_absolute():
+        path = (Path.cwd() / path).resolve()
+    try:
+        report, _expected = _run_one(path, args)
+    except Exception as exc:
+        print(f"[ENGINE ERROR] {type(exc).__name__}: {exc}", file=sys.stderr)
+        print(f"             exit {RC_TOOL_ERROR} = the tool failed; this is not a "
+              f"verdict.", file=sys.stderr)
+        return RC_TOOL_ERROR
+    print(report.pretty())
+    if getattr(report, "errors", None):
+        for e in report.errors:
+            print(f"[ENGINE ERROR] {e}", file=sys.stderr)
+        print(f"             exit {RC_TOOL_ERROR} = the tool failed; the verdict above "
+              f"is fail-safe, not a judgment.", file=sys.stderr)
+        return RC_TOOL_ERROR
+    return _RC.get(report.verdict, 1)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lgd_engine/gate/__init__.py

@@ -0,0 +1,4 @@
+"""lgd_engine.gate — GateEngine aggregates domain verdicts and enforces LGD laws."""
+from .engine import GateEngine, GateReport
+
+__all__ = ["GateEngine", "GateReport"]

lgd_engine/gate/engine.py

@@ -0,0 +1,155 @@
+"""GateEngine: aggregate domain-judge verdicts into one GateReport.
+
+- Runs each registered DomainJudge against the same ctx.
+- Honors L3-GATED: any critical reason → final verdict = reject.
+- Honors L2-EVIDENCED: go verdict with no evidence across all judges → hold.
+- Honors L1-RECORDED: caller (CLI/web) is expected to persist via LocalMemory;
+  engine itself does not write (keeps it pure & testable).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from ..judges.base import DomainJudge, JudgeVerdict
+
+
+@dataclass
+class GateReport:
+    verdict: str                          # go | hold | reject
+    per_judge: Dict[str, Dict[str, Any]] = field(default_factory=dict)
+    reasons: List[Dict[str, str]] = field(default_factory=list)
+    evidence: List[Dict[str, str]] = field(default_factory=list)
+    law_enforcements: List[str] = field(default_factory=list)
+    # Judges that raised. The verdict stays fail-safe (reject), but a consumer
+    # must be able to tell "the tool broke" from "the change is rejected" —
+    # otherwise a broken install reads as a legitimate veto and the CLI exits 2
+    # exactly like a real REJECT (red team S7 2026-11-04).
+    errors: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "verdict": self.verdict,
+            "per_judge": self.per_judge,
+            "reasons": self.reasons,
+            "evidence": self.evidence,
+            "law_enforcements": self.law_enforcements,
+            "errors": self.errors,
+        }
+
+    def pretty(self) -> str:
+        """Human-readable gate report for CLI."""
+        lines = []
+        badge = {"go": "✅ GO", "hold": "🟡 HOLD", "reject": "🔴 REJECT"}[self.verdict]
+        lines.append("=" * 60)
+        lines.append(f"GATE VERDICT: {badge}")
+        lines.append("=" * 60)
+        if self.law_enforcements:
+            lines.append("[LGD law enforcements]")
+            for e in self.law_enforcements:
+                lines.append(f"  - {e}")
+            lines.append("")
+        lines.append("[Per-judge verdicts]")
+        for dom, v in self.per_judge.items():
+            lines.append(f"  · {dom}: {v['verdict'].upper()}  "
+                         f"({len(v['reasons'])} reasons, {len(v['evidence'])} evidence)")
+        lines.append("")
+        lines.append("[Reason chain]")
+        for r in self.reasons:
+            lines.append(f"  [{r['level'].upper():8}] {r['rule']}")
+            lines.append(f"            {r['detail']}")
+        lines.append("")
+        lines.append("[Evidence cited]")
+        if not self.evidence:
+            lines.append("  (none)")
+        for e in self.evidence:
+            lines.append(f"  - ({e['kind']}) {e['ref']}")
+        lines.append("=" * 60)
+        return "\n".join(lines)
+
+
+class GateEngine:
+    """Aggregates N DomainJudge instances into one GateReport."""
+
+    def __init__(self, judges: List[DomainJudge] | None = None) -> None:
+        self.judges: List[DomainJudge] = list(judges or [])
+
+    def register(self, judge: DomainJudge) -> None:
+        self.judges.append(judge)
+
+    # ------------------------------------------------------------------ run
+    def evaluate(self, ctx: Dict[str, Any]) -> GateReport:
+        per_judge: Dict[str, Dict[str, Any]] = {}
+        all_reasons: List[Dict[str, str]] = []
+        all_evidence: List[Dict[str, str]] = []
+        law_hits: List[str] = []
+
+        any_critical = False
+        any_hold = False
+        any_go = False
+        errors: List[str] = []
+
+        for j in self.judges:
+            dom = getattr(j, "domain", j.__class__.__name__)
+            try:
+                v = j.evaluate(ctx)
+            except Exception as exc:
+                # A crashing judge is a critical failure: never let it pass.
+                # It is also NOT a verdict, so it is recorded as an error.
+                errors.append(f"{dom}: {type(exc).__name__}: {exc}")
+                v = {
+                    "verdict": "reject",
+                    "reasons": [{"rule": f"{dom}.exception",
+                                 "level": "critical",
+                                 "detail": f"judge raised: {exc!r}"}],
+                    "evidence": [],
+                }
+            per_judge[dom] = v
+
+            for r in v.get("reasons", []):
+                all_reasons.append(r)
+                if r["level"] == "critical":
+                    any_critical = True
+                elif r["level"] == "major":
+                    any_hold = True
+                # L2 downgrade is a hold signal regardless of how the judge tags
+                # it; detect by rule name, not by level (LGD-EVAL-2026-009 H1).
+                if r["rule"] == "L2-EVIDENCED":
+                    law_hits.append("L2-EVIDENCED: go-without-evidence downgraded")
+
+            for e in v.get("evidence", []):
+                all_evidence.append(e)
+
+            if v["verdict"] == "reject":
+                any_critical = True
+            elif v["verdict"] == "hold":
+                any_hold = True
+            elif v["verdict"] == "go":
+                any_go = True
+
+        # ---- L3-GATED: any critical → reject ----
+        if any_critical:
+            final = "reject"
+            # dedup
+            if "L3-GATED: critical veto forced reject" not in law_hits:
+                law_hits.append("L3-GATED: at least one critical rule fired → forced reject")
+        elif any_hold:
+            final = "hold"
+        elif any_go:
+            # ---- L2-EVIDENCED at aggregate level ----
+            if not all_evidence:
+                final = "hold"
+                law_hits.append("L2-EVIDENCED: aggregate go with zero evidence → hold")
+            else:
+                final = "go"
+        else:
+            final = "hold"  # no judges ran — safe default
+
+        return GateReport(
+            errors=errors,
+            verdict=final,
+            per_judge=per_judge,
+            reasons=all_reasons,
+            evidence=all_evidence,
+            law_enforcements=law_hits,
+        )

lgd_engine/judges/__init__.py

@@ -0,0 +1,18 @@
+"""lgd_engine.judges — domain adapters."""
+from .base import (
+    DomainJudge,
+    JudgeVerdict,
+    Reason,
+    Evidence,
+    VALID_VERDICTS,
+    VALID_LEVELS,
+)
+
+__all__ = [
+    "DomainJudge",
+    "JudgeVerdict",
+    "Reason",
+    "Evidence",
+    "VALID_VERDICTS",
+    "VALID_LEVELS",
+]

lgd_engine/judges/base.py

@@ -0,0 +1,66 @@
+"""DomainJudge Protocol + JudgeVerdict data structures.
+
+Fixed schema (shared with parallel Demo2 line):
+    JudgeVerdict = {
+        "verdict": "go" | "hold" | "reject",
+        "reasons": [{"rule": str, "level": "critical|major|minor", "detail": str}],
+        "evidence": [{"kind": str, "ref": str}],
+    }
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Protocol, runtime_checkable
+
+
+VALID_VERDICTS = ("go", "hold", "reject")
+VALID_LEVELS = ("critical", "major", "minor")
+
+
+@dataclass
+class Reason:
+    rule: str
+    level: str
+    detail: str
+
+    def __post_init__(self) -> None:
+        if self.level not in VALID_LEVELS:
+            raise ValueError(f"invalid reason level: {self.level}")
+
+
+@dataclass
+class Evidence:
+    kind: str   # e.g. "fda_recall", "fda_510k", "nmpa_recall", "internal_verification"
+    ref: str    # e.g. "Z-1924-2025", "K190204", URL, or local doc id
+
+
+@dataclass
+class JudgeVerdict:
+    verdict: str                       # go | hold | reject
+    reasons: List[Reason] = field(default_factory=list)
+    evidence: List[Evidence] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.verdict not in VALID_VERDICTS:
+            raise ValueError(f"invalid verdict: {self.verdict}")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "verdict": self.verdict,
+            "reasons": [asdict(r) for r in self.reasons],
+            "evidence": [asdict(e) for e in self.evidence],
+        }
+
+    @property
+    def has_critical(self) -> bool:
+        return any(r.level == "critical" for r in self.reasons)
+
+
+@runtime_checkable
+class DomainJudge(Protocol):
+    """Every domain adapter implements this. ctx is an input JSON dict."""
+
+    domain: str
+
+    def evaluate(self, ctx: Dict[str, Any]) -> Dict[str, Any]:  # pragma: no cover - protocol
+        ...