docs(backend): README with install, CLI, and programmatic usage

2026-06-19 16:01:25 -06:00
parent d4f3b204ef
commit 464a31be09
1 changed files with 68 additions and 0 deletions
@@ -0,0 +1,68 @@
+# 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`