Here's the reality: a claim that gets rejected by the payer costs you time, money, and a lot of rework. The goal of this module is to catch those problems before the claim ever leaves your building. But this isn't just a syntax checker — it runs four distinct validation layers, from schema enforcement all the way through historical denial-risk intelligence powered by your own denial database.
Layer 1 enforces mandatory billing elements via Pydantic models. Layer 2 checks structural EDI validity. Layer 3 runs a clinical audit for CPT/modifier issues. Layer 4 queries your denials_engine.db for historical denial patterns by CPT code and payer — flagging matches as HIGH DENIAL RISK before a claim ever reaches the clearinghouse.
The validator runs every 837 claim through a layered pipeline. Each layer catches different types of problems — and the last layer adds something most validators don't have: historical intelligence from your own denial data.
Pydantic models validate NPI format, CPT codes, modifiers, and ICD-10 against ANSI 5010 standards
Verifies EDI segment ordering, loop integrity, and required segment presence (ISA/GS/ST/CLM/SV1)
Flags CPT codes missing required modifiers and identifies coding deficiencies as HIGH AUDIT RISK
Queries denials_engine.db for historical denial patterns by CPT and payer — flags HIGH DENIAL RISK with CARC/RARC predictions
Catching errors before the payer does — including errors you didn't know to look for. The historical denial intelligence layer means the validator gets smarter over time. Every denial pattern your practice has seen gets fed back in, so the system flags high-risk claims before they repeat the same mistakes.
Every validated claim produces a structured record with severity classification, risk level, and recovery data. Here's what each column means so your team knows exactly how to act on the output.
| Column | Description |
|---|---|
| Severity | ERROR / HIGH AUDIT RISK / HIGH DENIAL RISK / PASS |
| Category | Finding category (e.g., CPT / Modifier, Denial Pattern) |
| Raw_Code | CPT code (digits only) |
| Risk_Level | High / Medium / Low / None |
| Recovery_Potential | Dollar estimate of recoverable revenue or N/A |
| Modifier_Required | Yes / No / N/A — from Layer 3 clinical audit |
| CARC_RARC_Potential | Predicted CARC + RARC codes based on historical denial patterns |
Cross-dependency: denials_engine.db required for Layer 4. The denial intelligence layer queries the SQLite database produced by the Recovery Engine pipeline. Place denials_engine.db in the same directory or pass --db-path at runtime.