Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,17 @@ Most governance tooling ships a dashboard and a compliance checkbox. This ships
from payer_agent_audit.governance import AuditChain
from payer_agent_audit.payer import ClinicianOfRecordControl, ClinicianOfRecordMissingError

chain = AuditChain(deployer_id="acme-health-prod") # hardened genesis
chain = AuditChain(deployer_id="acme-health-prod") # hardened genesis
try:
ClinicianOfRecordControl(chain).attest_denial(
case_ref="PA-12345",
is_medical_necessity_denial=True,
clinician=None, # an agent denies care, no human reviewer
clinician=None, # an agent denies care, no human reviewer
)
raise SystemExit("ungoverned denial went through") # never reached
raise SystemExit("ungoverned denial went through") # never reached
except ClinicianOfRecordMissingError:
pass # refused, and the refusal is on the chain
assert chain.verify() # POLICY_VIOLATION recorded, tamper-evident
pass # refused, and the refusal is on the chain
assert chain.verify() # POLICY_VIOLATION recorded, tamper-evident
```

2. **A UM-timeliness test, the breach not the happy path** — an autonomous decision that blows the deadline, and the ledger that records it:
Expand All @@ -50,16 +50,16 @@ Most governance tooling ships a dashboard and a compliance checkbox. This ships
from payer_agent_audit.payer import UMTimelinessControl, FundingType, RequestCategory
from datetime import datetime, timedelta, UTC

chain = AuditChain(deployer_id="acme-health-prod") # hardened genesis
chain = AuditChain(deployer_id="acme-health-prod") # hardened genesis
received = datetime(2026, 6, 1, 8, 0, tzinfo=UTC)
result = UMTimelinessControl(chain).check(
funding_type=FundingType.MEDICARE_ADVANTAGE,
category=RequestCategory.EXPEDITED_URGENT, # CMS-0057-F 72h
category=RequestCategory.EXPEDITED_URGENT, # CMS-0057-F 72h
request_received_at=received,
decision_made_at=received + timedelta(hours=80), # 80h > 72h
decision_made_at=received + timedelta(hours=80), # 80h > 72h
case_ref="PA-12345",
)
assert result.met is False # breach, recorded to the chain
assert result.met is False # breach, recorded to the chain
assert chain.verify()
```

Expand Down
23 changes: 14 additions & 9 deletions WORKED_EXAMPLE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The agent reaches a determination on case `PA-12345` — a Medicare Advantage ex

```python
received = datetime(2026, 6, 1, 8, 0, tzinfo=UTC)
decided = received + timedelta(hours=80) # the agent decided at hour 80
decided = received + timedelta(hours=80) # the agent decided at hour 80
```

### 3. The envelope catches the out-of-envelope case
Expand All @@ -34,8 +34,11 @@ ClinicianOfRecordControl(chain).attest_denial(
case_ref="PA-12345",
is_medical_necessity_denial=True,
clinician=ClinicianOfRecord(
clinician_name="Dr. A. Reviewer", license_number="TX-12345",
npi="1234567890", reviewed=True, same_or_similar_specialty=True,
clinician_name="Dr. A. Reviewer",
license_number="TX-12345",
npi="1234567890",
reviewed=True,
same_or_similar_specialty=True,
),
)
```
Expand All @@ -50,7 +53,7 @@ result = UMTimelinessControl(chain).check(
decision_made_at=decided,
case_ref="PA-12345",
)
assert result.met is False # the breach is real, not the happy path
assert result.met is False # the breach is real, not the happy path
```

### 4. The audit entry
Expand All @@ -66,11 +69,13 @@ assert chain.verify()
The breach is an operational-risk signal — **not** a clinical determination. It escalates the agent's DEFCON autonomy state to `HALT`, and a sovereign veto engages so the agent cannot keep issuing this decision class until a human re-authorizes it.

```python
defcon.evaluate(RiskMetrics(breach_rate=0.35)) # -> DEFCON.HALT
veto.trigger(reason=VetoReason.UM_TIMELINESS_AT_RISK,
triggered_by="compliance-monitor",
description="PA-12345 decided at 80h vs the 72h CMS-0057-F floor")
assert veto.allow_execution() is False # halted pending human re-auth
defcon.evaluate(RiskMetrics(breach_rate=0.35)) # -> DEFCON.HALT
veto.trigger(
reason=VetoReason.UM_TIMELINESS_AT_RISK,
triggered_by="compliance-monitor",
description="PA-12345 decided at 80h vs the 72h CMS-0057-F floor",
)
assert veto.allow_execution() is False # halted pending human re-auth
```

## Actual output
Expand Down
Loading