# Cyclone Backend — X12 837P Parser

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

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

## CLI

```bash
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

```python
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

```bash
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`