Metadata-Version: 2.4
Name: x12sdk
Version: 1.0.0
Summary: Typed Pydantic models and a streaming SDK/CLI for HIPAA ASC X12 5010 health care transactions (837P, 837I, 835, 834, 270, 271, 276, 277).
Author: owgreen-dev
License: Apache-2.0
Project-URL: Homepage, https://github.com/owgreen-dev/x12sdk
Project-URL: Repository, https://github.com/owgreen-dev/x12sdk
Project-URL: Issues, https://github.com/owgreen-dev/x12sdk/issues
Project-URL: Changelog, https://github.com/owgreen-dev/x12sdk/blob/main/CHANGELOG.md
Project-URL: Upstream (LinuxForHealth x12), https://github.com/LinuxForHealth/x12
Keywords: x12,edi,hipaa,837,835,834,270,271,276,277,claims,pydantic
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pydantic<3,>=2
Requires-Dist: pydantic-settings>=2
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: dev
Requires-Dist: pytest>=7.1; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: pre-commit>=2.14; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Dynamic: license-file

# x12sdk

Typed [Pydantic v2](https://docs.pydantic.dev/) models and a streaming SDK/CLI
for HIPAA ASC X12 5010 health care transactions.

![License](https://img.shields.io/github/license/owgreen-dev/x12sdk)
![CI](https://github.com/owgreen-dev/x12sdk/actions/workflows/continuous-integration.yml/badge.svg)
![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)

> x12sdk is the maintained continuation of
> [LinuxForHealth x12](https://github.com/LinuxForHealth/x12), which stopped at
> 0.57.0 in June 2022. It runs on **Pydantic v2 and Python 3.10–3.13**.

Supported transaction sets:

| Set | Implementation | What it is |
|---|---|---|
| 837P | 005010X222A2 | Professional claim |
| 837I | 005010X223A3 | Institutional claim |
| 835 | 005010X221A1 | Claim payment / remittance advice |
| 834 | 005010X220A1 | Benefit enrollment and maintenance |
| 270 / 271 | 005010X279A1 | Eligibility inquiry / response |
| 276 / 277 | 005010X212 | Claim status inquiry / response |

Every transaction is parsed into a validated Pydantic model and can be
serialized back to X12; the test suite asserts that round trip reproduces
each sample file byte for byte.

## Install

```shell
pip install x12sdk
```

From source:

```shell
git clone https://github.com/owgreen-dev/x12sdk
cd x12sdk
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -e .
```

## SDK

The `x12sdk.io` module streams either raw segments or validated transaction
models from a file.

Stream segments (each segment becomes its name plus a list of fields):

```python
from x12sdk.io import X12SegmentReader

with X12SegmentReader("/home/edi/270.x12") as r:
    for segment_name, segment_fields in r.segments():
        print(segment_name, segment_fields)
```

Stream models (the payload is validated; one model per transaction set):

```python
from x12sdk.io import X12ModelReader

with X12ModelReader("/home/edi/270.x12") as r:
    for model in r.models():
        print(model.header)   # common attributes: header, footer
        print(model.footer)
        model.x12()           # serialize back to X12
```

## CLI

```shell
x12sdk --help
usage: x12sdk [-h] [-s | -m] [-x] [-p] [-d] file

The x12sdk CLI parses and validates X12 messages.
Messages are returned in JSON format in either a segment or transactional format.

positional arguments:
  file              The path to a ASC X12 file

options:
  -h, --help        show this help message and exit
  -s, --segment     Returns X12 segments
  -m, --model       Returns X12 models
  -x, --exclude     Exclude fields set to None in model output
  -p, --pretty      Pretty print output
  -d, --delimiters  Include X12 delimiters in output (model mode only)
```

```shell
x12sdk -s -p demo-file/demo.270   # segments
x12sdk -m -p demo-file/demo.270   # models
```

## Migrating from `linuxforhealth-x12`

| before | after |
|---|---|
| `pip install linuxforhealth-x12` | `pip install x12sdk` |
| `from linuxforhealth.x12.io import X12ModelReader` | `from x12sdk.io import X12ModelReader` |
| `lfhx12 -m -p file.x12` | `x12sdk -m -p file.x12` |
| `lfhx12-api` (FastAPI endpoint) | removed; wrap the SDK in your own service |

See [CHANGELOG.md](CHANGELOG.md) for everything that changed.

## Development

```shell
pip install -e ".[dev]"
ruff check src
pytest --cov
```

Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md) (Apache-2.0,
DCO sign-off, no copyrighted standards text, no real PHI). To add a
transaction set, see [repo-docs/NEW_TRANSACTION.md](repo-docs/NEW_TRANSACTION.md);
the design is described in [repo-docs/DESIGN.md](repo-docs/DESIGN.md).

## Provenance and related work

x12sdk is a fork of **[LinuxForHealth x12](https://github.com/LinuxForHealth/x12)**
by Dixon Whitmire and the LinuxForHealth contributors (IBM), released under
the Apache License 2.0. The models, parser, readers, and test corpus
originate there; x12sdk exists to keep that work usable on current Python
and Pydantic. The original LICENSE is retained, and attribution and
trademark notes are in [NOTICE](NOTICE) and [TRADEMARK.md](TRADEMARK.md).
x12sdk is not affiliated with or endorsed by IBM, LinuxForHealth, or the
Linux Foundation.

- **[MdClarity/x12](https://github.com/MdClarity/x12)** — an independent
  fork by MD Clarity (Cary Lee) that completed a Pydantic v2 migration and
  added type checking and fuzzing in 2026. x12sdk's port is written
  separately from the 2022 upstream; their work is acknowledged here and
  their fixes are welcome upstream in x12sdk.
- **[pyx12](https://github.com/azoner/pyx12)** — the long-standing Python X12
  validator/converter (XML/dict output, map-driven). Choose pyx12 for
  validation against X12 maps; choose x12sdk for typed Python models.
- **[edi-835-parser](https://github.com/keiron-stoddart/edi-835-parser)** —
  a popular 835-only parser with pandas output.

## License

Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
