payer-agent-audit 0.1.4__py3-none-any.whl

payer_agent_audit/__init__.py

@@ -0,0 +1,63 @@
+"""Governance patterns for autonomous AI agents in health-insurance / payer
+operations (NAIC umbrella).
+
+These are reference IP for adoption — documented, tested patterns — NOT a
+deployed control operating in production. The deployer's substrate is the
+production deployment. See LIMITATIONS.md and DISCLAIMER.md.
+
+This library makes NO medical-necessity or clinical determination. A payer
+coverage decision is a benefit adjudication under insurance law (NAIC /
+state DOI / ERISA 29 CFR 2560.503-1 / CMS / ACA 45 CFR 147.136), distinct
+from FDA Software-as-a-Medical-Device regulation. See the payer-not-FDA-SaMD
+boundary in LIMITATIONS.md.
+
+The headline primitives and controls are re-exported here for convenience::
+
+    from payer_agent_audit import AuditChain, SovereignVeto, DEFCONMachine
+    from payer_agent_audit import UMTimelinessControl, FundingType
+"""
+
+from __future__ import annotations
+
+from payer_agent_audit.governance import (
+    DEFCON,
+    AuditChain,
+    DEFCONMachine,
+    EffectiveChallengeHarness,
+    SovereignVeto,
+    check_a2_to_a3_promotion,
+)
+from payer_agent_audit.payer import (
+    AppealIROControl,
+    ClinicianOfRecordControl,
+    FundingType,
+    RequestCategory,
+    UMTimelinessControl,
+    obligations_for,
+)
+from payer_agent_audit.schemas import (
+    AuditEvent,
+    AuditEventType,
+    AutonomyLevel,
+)
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "AppealIROControl",
+    "AuditChain",
+    "AuditEvent",
+    "AuditEventType",
+    "AutonomyLevel",
+    "ClinicianOfRecordControl",
+    "DEFCON",
+    "DEFCONMachine",
+    "EffectiveChallengeHarness",
+    "FundingType",
+    "RequestCategory",
+    "SovereignVeto",
+    "UMTimelinessControl",
+    "__version__",
+    "check_a2_to_a3_promotion",
+    "obligations_for",
+]

payer_agent_audit/_normalize.py

@@ -0,0 +1,41 @@
+"""Shared identity normalization for governance guards.
+
+The self-attestation (P1), self-clear (P2), effective-challenge (P5), and
+ERISA full-and-fair-review independence (appeal/IRO) guards all compare
+caller-supplied principal identifiers. A naive ``==`` (or even
+``.strip().casefold()``) is defeated by Unicode confusables and zero-width
+characters — e.g. a fullwidth ``ａgent`` (U+FF41) or a zero-width-space
+injection reads as a *different* string and slips past the guard, letting an
+agent self-attest or self-clear. ``normalize_principal_id`` closes that class
+by applying NFKC compatibility folding, stripping the zero-width set, and
+casefolding, so equivalent identifiers compare equal.
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+# Zero-width and BOM characters that ``str.strip()`` does NOT remove but that
+# must not be allowed to disguise one principal as another.
+_ZERO_WIDTH = dict.fromkeys(
+    [
+        0x200B,  # ZERO WIDTH SPACE
+        0x200C,  # ZERO WIDTH NON-JOINER
+        0x200D,  # ZERO WIDTH JOINER
+        0x2060,  # WORD JOINER
+        0xFEFF,  # ZERO WIDTH NO-BREAK SPACE / BOM
+    ]
+)
+
+
+def normalize_principal_id(value: str) -> str:
+    """Return a canonical form of a principal identifier for guard comparison.
+
+    NFKC compatibility-folds confusables (fullwidth/compatibility forms),
+    removes zero-width characters, strips surrounding whitespace, and
+    casefolds. Two identifiers that a human would read as the same principal
+    normalize to the same string; a blank-after-normalization id returns "".
+    """
+    folded = unicodedata.normalize("NFKC", value)
+    folded = folded.translate(_ZERO_WIDTH)
+    return folded.strip().casefold()

payer_agent_audit/agents/__init__.py

@@ -0,0 +1 @@
+"""Reference agents (documented patterns, not deployed controls)."""

payer_agent_audit/cli.py

@@ -0,0 +1,117 @@
+"""payer-audit CLI — verify an audit chain + show obligation routing.
+
+Deployer-facing entry point (``payer-audit``). Stdlib-only. Subcommands:
+
+    verify   --jsonl <path>             verify a JSONL audit chain
+    info                                print version + the five primitives
+    obligations --funding <t> --category <c>
+                                        print the obligation routing for a
+                                        (funding_type, request category)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from payer_agent_audit import __version__
+from payer_agent_audit.governance.audit_chain import AuditChain, AuditChainTamperError
+from payer_agent_audit.payer.funding_type import (
+    FundingType,
+    RequestCategory,
+    obligations_for,
+)
+
+_PRIMITIVES = [
+    "P1 AutonomyLadder level-gate (independent attestation, advisory-labeled)",
+    "P2 SovereignVeto (mandatory authorizer in production, un-self-clearable)",
+    "P3 AuditChain (genesis-branching verifier, witness anchor in production)",
+    "P4 DEFCONMachine (transition-direction guard)",
+    "P5 EffectiveChallengeHarness (challenger != primary, attested independence)",
+]
+
+
+def _cmd_info(_: argparse.Namespace) -> int:
+    print(f"payer-agent-audit {__version__}")
+    print("aligned to the NAIC Model Bulletin framework · module (a) health-payer")
+    print("Five corrected-spec primitives:")
+    for p in _PRIMITIVES:
+        print(f"  - {p}")
+    print(
+        "\nReference IP for adoption — NOT a deployed control. Makes no "
+        "medical-necessity / clinical determination. See LIMITATIONS.md."
+    )
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    path = Path(args.jsonl)
+    if not path.exists():
+        print(f"error: {path} not found", file=sys.stderr)
+        return 2
+    try:
+        chain = AuditChain(log_file=path)
+        chain.verify_strict()
+    except AuditChainTamperError as exc:
+        print(f"TAMPER DETECTED: {exc}", file=sys.stderr)
+        return 1
+    print(f"OK: chain verified ({len(chain)} events), head={chain.chain_head()[:16]}...")
+    return 0
+
+
+def _cmd_obligations(args: argparse.Namespace) -> int:
+    # argparse `choices=` (build_parser) already restricts --funding/--category
+    # to valid enum values, so these conversions cannot raise here.
+    funding = FundingType(args.funding)
+    category = RequestCategory(args.category)
+    ob = obligations_for(funding, category)
+    print(f"funding_type        : {ob.funding_type.value}")
+    print(f"category            : {ob.category.value}")
+    print(f"primary_regulator   : {ob.primary_regulator}")
+    dl = ob.timeliness.deadline
+    print(f"timeliness_deadline : {dl if dl is not None else 'deployer-supplied (state-specific)'}")
+    print(f"timeliness_verified : {ob.timeliness.verified}")
+    print(f"citation            : {ob.timeliness.citation}")
+    print(f"appeal_regime       : {ob.appeal_regime}")
+    print(f"external_review     : {ob.external_review_citation}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="payer-audit", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_info = sub.add_parser("info", help="print version + the five primitives")
+    p_info.set_defaults(func=_cmd_info)
+
+    p_verify = sub.add_parser("verify", help="verify a JSONL audit chain")
+    p_verify.add_argument("--jsonl", required=True, help="path to the JSONL chain")
+    p_verify.set_defaults(func=_cmd_verify)
+
+    p_ob = sub.add_parser("obligations", help="print obligation routing")
+    p_ob.add_argument(
+        "--funding",
+        required=True,
+        choices=[f.value for f in FundingType],
+        help="funding type",
+    )
+    p_ob.add_argument(
+        "--category",
+        required=True,
+        choices=[c.value for c in RequestCategory],
+        help="request category",
+    )
+    p_ob.set_defaults(func=_cmd_obligations)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    result: int = args.func(args)
+    return result
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

payer_agent_audit/governance/__init__.py

@@ -0,0 +1,82 @@
+"""Governance primitives for payer-agent-audit.
+
+The five corrected-spec primitives:
+    P1  AutonomyLadder level-gate (autonomy_ladder.py)
+    P2  SovereignVeto             (sovereign_veto.py)
+    P3  AuditChain                (audit_chain.py)
+    P4  DEFCONMachine             (defcon.py)
+    P5  EffectiveChallengeHarness (effective_challenge_harness.py)
+"""
+
+from __future__ import annotations
+
+from payer_agent_audit.governance.audit_chain import AuditChain, AuditChainTamperError
+from payer_agent_audit.governance.autonomy_ladder import (
+    ADVISORY,
+    Attestation,
+    PromotionEvidence,
+    PromotionGateNotMet,
+    PromotionGateReport,
+    check_a2_to_a3_promotion,
+    required_oversight,
+)
+from payer_agent_audit.governance.defcon import (
+    DEFCON,
+    DEFCONMachine,
+    DEFCONOverrideRejectedError,
+    RiskMetrics,
+)
+from payer_agent_audit.governance.effective_challenge_harness import (
+    ChallengeReport,
+    ChallengerNotIndependentError,
+    EffectiveChallengeHarness,
+    IndependenceAttestation,
+)
+from payer_agent_audit.governance.sovereign_veto import (
+    Authorizer,
+    InMemoryVetoStateStore,
+    SovereignVeto,
+    VetoBlockedError,
+    VetoReason,
+    VetoRecord,
+    VetoStateStore,
+)
+from payer_agent_audit.governance.witness_anchor import (
+    InMemoryWitness,
+    RekorWitness,
+    WitnessReceipt,
+    WitnessRegister,
+    anchor_to_witness,
+)
+
+__all__ = [
+    "ADVISORY",
+    "Attestation",
+    "AuditChain",
+    "AuditChainTamperError",
+    "Authorizer",
+    "ChallengeReport",
+    "ChallengerNotIndependentError",
+    "DEFCON",
+    "DEFCONMachine",
+    "DEFCONOverrideRejectedError",
+    "EffectiveChallengeHarness",
+    "InMemoryVetoStateStore",
+    "InMemoryWitness",
+    "IndependenceAttestation",
+    "PromotionEvidence",
+    "PromotionGateNotMet",
+    "PromotionGateReport",
+    "RekorWitness",
+    "RiskMetrics",
+    "SovereignVeto",
+    "VetoBlockedError",
+    "VetoReason",
+    "VetoRecord",
+    "VetoStateStore",
+    "WitnessReceipt",
+    "WitnessRegister",
+    "anchor_to_witness",
+    "check_a2_to_a3_promotion",
+    "required_oversight",
+]