Python module + CLI for parsing X12 837P professional claim files into one validated JSON per claim. Output is consumed by the Cyclone Vite/React frontend (later via a FastAPI service).

Install

cd backend
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"

CLI

python -m cyclone.cli parse-837 path/to/837p.txt --output-dir ./claims

Options:

--payer {co_medicaid,generic_837p} — default co_medicaid
--strict — promote warnings to errors
--max-retries N — stub in v1 (no auto-fix yet)
--include-raw-segments / --no-raw-segments — default: include
--log-level {DEBUG,INFO,WARNING,ERROR}

Exit codes:

0 — every claim parsed
2 — file-level failure (no envelope, no claims)
1 — unexpected exception

Output

claims/
├── claim-991102977-20260611-CLM001.json   # one per claim
├── claim-991102977-20260611-CLM002.json
└── summary.json                            # batch summary

Programmatic use

from pathlib import Path
from cyclone.parsers.parse_837 import parse
from cyclone.parsers.payer import PayerConfig
from cyclone.parsers.writer import write_outputs

result = parse(Path("input.txt").read_text(), PayerConfig.co_medicaid())
write_outputs(result, Path("./claims"))
print(f"passed={result.summary.passed} failed={result.summary.failed}")

Tests

pytest -v

The CLI smoke test against docs/prodfiles/837p-from-axiscare/*.txt is auto-skipped if no production files are present.

Spec & plan

Design: docs/superpowers/specs/2026-06-19-cyclone-837p-parser-design.md
Plan: docs/superpowers/plans/2026-06-19-cyclone-837p-parser.md