cyclone/.superpowers/skills/cyclone-edi/references/parsers.md

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.