feat(sp-skill-catalog): add cyclone-edi skill (parser/validator conventions)

2026-06-21 12:00:18 -06:00
parent b0f0bd9d73
commit 4bdca6168c
2 changed files with 233 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Cyclone EDI parsers — flat catalog
+
+Every parser module under `backend/src/cyclone/parsers/` (one row per
+file), its transaction type, its public entry signature, its result
+model, its primary fixture, and any payer-specific variant. The
+companion Pydantic model is in a co-located `models_<edi>.py`; the
+segment walker uses `tokenize()` from `segments.py` and never parses
+raw text inline.
+
+| Module | EDI type | Public entry signature | Result model | Primary fixture(s) | Payer variant |
+|---|---|---|---|---|---|
+| `parse_837.py` | 837P (Professional Claim) | `parse(text, payer_config: PayerConfig, input_file="") -> ParseResult` | `cyclone.parsers.models.ParseResult` | `minimal_837p.txt`, `co_medicaid_837p.txt` | `PayerConfig` (CO Medicaid default) |
+| `parse_835.py` | 835 (ERA / Remittance) | `parse(text, payer_config: PayerConfig835, input_file="") -> ParseResult835` | `cyclone.parsers.models_835.ParseResult835` | `minimal_835.txt`, `co_medicaid_835.txt`, `unbalanced_835.txt` | `PayerConfig835` |
+| `parse_999.py` | 999 (Implementation ACK) | `parse_999_text(text, *, input_file="") -> ParseResult999` | `cyclone.parsers.models_999.ParseResult999` | `minimal_999.txt`, `minimal_999_rejected.txt` | none — single-shape ack |
+| `parse_277ca.py` | 277CA (Claim ACK) | `parse_277ca_text(text, *, input_file="") -> ParseResult277CA` | `cyclone.parsers.models_277ca.ParseResult277CA` | `minimal_277ca.txt`, `minimal_277ca_rejected_only.txt`, `minimal_277ca_st277.txt` | `PayerConfig277CA` (config-driven) |
+| `parse_270.py` | 270 (Eligibility Inquiry) | `parse(text, *, input_file="") -> ParseResult270` | `cyclone.parsers.models_270.ParseResult270` | `minimal_270.txt` | reuses `PayerConfig` shape |
+| `parse_271.py` | 271 (Eligibility Response) | `parse(text, *, input_file="") -> ParseResult271` | `cyclone.parsers.models_271.ParseResult271` | `minimal_271.txt` | reuses `PayerConfig` shape |
+| `parse_ta1.py` | TA1 (Interchange ACK) | `parse_ta1_text(text, *, input_file="") -> ParseResultTa1` | `cyclone.parsers.models_ta1.ParseResultTa1` | `minimal_ta1.txt` | none — single-shape ack |
+
+Companion modules (not parsers, but shipped alongside):
+
+| Module | Role |
+|---|---|
+| `segments.py` | `Delimiters`, `_detect_delimiters`, `tokenize(text) -> list[list[str]]` |
+| `models.py` | Pydantic models for 837P (`ParseResult`, `ClaimOutput`, `Envelope`, `BatchSummary`, `ValidationIssue`, `ValidationReport`, …) |
+| `models_835.py` / `models_270.py` / `models_271.py` / `models_277ca.py` / `models_999.py` / `models_ta1.py` | Pydantic models for each transaction type |
+| `payer.py` | `PayerConfig` + `PayerConfig835` factories |
+| `exceptions.py` | `CycloneParseError`, `CycloneValidationError` |
+| `cas_codes.py` | CARC lookup: `reason_label(group, reason)`, `all_known_codes()`, `LAST_UPDATED` |
+| `validator.py` | 837P rules: R010–R100, R200–R210; `validate(claim, config) -> ValidationReport` |
+| `validator_835.py` | 835 rules: `R835_*` (e.g. `R835_BPR01_handling_code_allowed`); `validate(result, cfg) -> ValidationReport` |
+| `serialize_270.py` / `serialize_837.py` / `serialize_999.py` | Outbound (Cyclone → payer) serializers — mirror of `parse_*` |
+| `writer.py` / `writer_835.py` | Output writers (one JSON per claim) |
+| `batch_ack_builder.py` | `build_ack_for_batch` — produces a 999 for a parsed 837 batch |
+| `__init__.py` | Lazy PEP 562 re-exports (`parse`, `parse_835`, `parse_999`, `parse_270`, `parse_271`, `parse_277ca`, plus all models) |
+
+Fixture rule: every parser ships at least one flat fixture in
+`backend/tests/fixtures/<edi>-sample.txt`. Prodfiles sources live in
+`docs/prodfiles/{837p-from-axiscare,835fromco,FromHPE,claims}/` — copy
+from there, never reach in from a test.