Metadata-Version: 2.4
Name: validedi
Version: 0.4.0
Summary: A modern, configuration-driven X12 EDI parser and validator for healthcare transactions with optional LLM-powered explanations and structured data extraction
Author-email: ValidEDI Team <validedi@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/validedi
Project-URL: Documentation, https://github.com/yourusername/validedi#readme
Project-URL: Repository, https://github.com/yourusername/validedi
Project-URL: Issues, https://github.com/yourusername/validedi/issues
Project-URL: Changelog, https://github.com/yourusername/validedi/blob/main/CHANGELOG.md
Keywords: edi,x12,healthcare,837,835,834,parser,validator,llm,ai,claims,remittance,enrollment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.17.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# ValidEDI

**A modern, configuration-driven X12 EDI parser and validator for healthcare transactions with optional LLM-powered explanations.**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What is ValidEDI?

ValidEDI is a Python library for parsing and validating healthcare EDI (Electronic Data Interchange) files. It supports the most common X12 transaction types used in healthcare:

- **837P** - Professional Health Care Claims
- **837I** - Institutional Health Care Claims  
- **835** - Health Care Claim Payment/Remittance Advice
- **834** - Benefit Enrollment and Maintenance

### Key Features

✅ **Parse EDI Files** - Convert X12 EDI into structured Python objects  
✅ **Validate Transactions** - 60+ validation rules with plain-English error messages  
✅ **Configuration-Driven** - All rules and codes in YAML files, not hardcoded  
✅ **LLM-Powered Explanations** - Optional AI-powered plain-English reports (works with ANY LLM)  
✅ **Loop Navigation** - Hierarchical loop structure for easy data access  
✅ **Type-Safe** - Full Pydantic v2 models with type hints  
✅ **Extensible** - Add custom validation rules and code sets  
✅ **Production-Ready** - Thread-safe, well-tested, comprehensive error handling

---

## Quick Start

### Installation

```bash
pip install validedi
```

### Parse an EDI File

```python
from validedi import parse

# Parse from file path
result = parse('claim.edi')

# Access parsed data
print(f"Transaction: {result.envelope.transaction_type}")
print(f"From: {result.envelope.sender_id}")
print(f"To: {result.envelope.receiver_id}")
print(f"Loops: {len(result.loops)}")
```

### Validate an EDI File

```python
from validedi import validate

# Validate the file
result = validate('claim.edi')

# Check results
if result.is_valid:
    print("✅ File is valid!")
else:
    print(f"❌ Found {result.error_count} errors")
    for error in result.errors:
        print(f"  • {error.message}")
```

### Get Plain-English Explanations (Optional)

```python
from validedi import parse, validate
from validedi.llm import explain

# Parse and validate
edi_result = parse('claim.edi')
val_result = validate(edi_result)

# Option 1: With your own LLM (OpenAI, Groq, Bedrock, Gemini, etc.)
from openai import OpenAI
client = OpenAI(api_key="your-key")

def my_llm(prompt: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

result = explain(edi_result, val_result, llm=my_llm)
print(result.report)

# Option 2: Without LLM (rule-based templates)
result = explain(edi_result, val_result)
print(result.report)
```

### Ask Questions About Your EDI File

```python
from validedi.llm import ask_followup

# Ask questions in plain English
answer = ask_followup(
    "What is the total billed amount?",
    edi_result,
    val_result,
    llm=my_llm
)
print(answer)
```

---

## Why ValidEDI?

### vs. Other EDI Libraries

| Feature | ValidEDI | Others |
|---------|----------|--------|
| Configuration-Driven | ✅ YAML files | ❌ Hardcoded |
| Plain-English Errors | ✅ Yes | ❌ Technical codes |
| LLM Integration | ✅ Any provider | ❌ None |
| Loop Navigation | ✅ Hierarchical | ⚠️ Flat segments |
| Type Safety | ✅ Pydantic v2 | ⚠️ Dicts |
| Extensible | ✅ Easy | ⚠️ Difficult |
| Modern Python | ✅ 3.8+ | ⚠️ Legacy |

### Configuration-Driven Architecture

Unlike other libraries that hardcode validation rules, ValidEDI uses YAML configuration files:

```yaml
# validedi/config/rules/rules_837.yaml
rules:
  - id: 'CLM01_REQUIRED'
    type: 'required_element'
    target: 'CLM01'
    severity: 'error'
    message: 'CLM01 (Patient Control Number) is blank'
    suggestion: 'CLM01 must be a unique identifier for the claim'
```

This means you can:
- Add new validation rules without changing code
- Customize rules for your specific needs
- Version control your validation logic
- Share configurations across teams

---

## Supported Transaction Types

### 837P - Professional Claims
Outpatient and office-based healthcare services billed with CPT codes.

**Use Cases:**
- Doctor office visits
- Outpatient procedures
- Laboratory services
- Durable medical equipment

### 837I - Institutional Claims
Inpatient and facility-based healthcare services billed with revenue codes.

**Use Cases:**
- Hospital inpatient stays
- Emergency room visits
- Skilled nursing facilities
- Home health services

### 835 - Remittance Advice
Payer explanation of claim payments and adjustments.

**Use Cases:**
- Payment reconciliation
- Claim status tracking
- Adjustment reason analysis
- Accounts receivable management

### 834 - Benefit Enrollment
Member insurance enrollment, changes, and terminations.

**Use Cases:**
- New member enrollment
- Coverage changes
- Dependent additions
- Terminations

---

## Documentation

### Quick Start
- [Quick Start Guide](QUICKSTART.md) - Get started in 5 minutes
- [Basic Usage Examples](examples/basic_usage.py) - Common use cases

### Deep Dive
- [Architecture Deep Dive](docs/ARCHITECTURE.md) - How ValidEDI works internally
- [Configuration Guide](docs/CONFIGURATION.md) - Customize validation rules

### LLM Integration
- [LLM Guide](docs/LLM_GUIDE.md) - AI-powered explanations
- [LLM Examples](examples/llm_usage.py) - 8+ provider examples
- [Interactive Chatbot](examples/llm_chatbot.py) - CLI chatbot

### Advanced
- [API Reference](docs/API_REFERENCE.md) - Complete API documentation
- [Custom Validation](docs/CUSTOM_VALIDATION.md) - Add your own rules
- [Publishing Guide](PUBLISH_TO_PYPI.md) - Deploy to PyPI

---

## Examples

### Parse and Navigate Loops

```python
from validedi import parse

result = parse('claim.edi')

# Navigate hierarchical loops
for loop in result.loops:
    if loop.loop_id == '2000A':  # Billing Provider
        for segment in loop.segments:
            if segment.segment_id == 'NM1':
                print(f"Provider: {segment.elements[2]}")
```

### Custom Validation

```python
from validedi import validate

# Validate with custom rules
result = validate('claim.edi')

# Access detailed validation results
for error in result.errors:
    print(f"[{error.code}] {error.segment_id}: {error.message}")
    if error.suggestion:
        print(f"  Fix: {error.suggestion}")
```

### Batch Processing

```python
from validedi import parse, validate
import glob

for filepath in glob.glob('*.edi'):
    edi_result = parse(filepath)
    val_result = validate(edi_result)
    
    print(f"{filepath}: {val_result.summary}")
```

### Interactive Chatbot

```bash
python examples/llm_chatbot.py claim.edi
```

```
You: What is the total billed amount?
Bot: The total billed amount is $4,250.00 across 3 claims.

You: Are there any errors?
Bot: There is 1 warning: CLM06 is missing on Claim #2.

You: quit
👋 Goodbye!
```

---

## Architecture Highlights

### 1. Configuration-Driven Design
All validation rules, code sets, and transaction definitions are in YAML files:

```
validedi/config/
├── transactions/     # Transaction definitions (837P, 837I, 835, 834)
├── rules/           # Validation rules
├── code_sets/       # Code value lists
└── registry.yaml    # Transaction registry
```

### 2. Hierarchical Loop Structure
EDI segments are organized into hierarchical loops for easy navigation:

```python
Loop 2000A (Billing Provider)
  ├── Segment NM1 (Name)
  ├── Segment N3 (Address)
  └── Loop 2000B (Subscriber)
      ├── Segment NM1 (Name)
      └── Loop 2300 (Claim)
          ├── Segment CLM (Claim Info)
          └── Loop 2400 (Service Line)
              └── Segment SV1 (Service)
```

### 3. Type-Safe Models
Full Pydantic v2 models with type hints:

```python
class ParsedEDI(BaseModel):
    envelope: EnvelopeMeta
    loops: List[Loop]
    segments: List[Segment]
    raw_content: str

class ValidationResult(BaseModel):
    is_valid: bool
    error_count: int
    errors: List[ValidationError]
    summary: str
```

### 4. LLM-Agnostic Integration
Works with ANY LLM through a simple callable interface:

```python
# Works with OpenAI, Groq, Bedrock, Gemini, Anthropic, local models, etc.
def my_llm(prompt: str) -> str:
    return response

result = explain(edi_result, val_result, llm=my_llm)
```

---

## Validation Rules

ValidEDI includes 60+ validation rules across 4 categories:

### Envelope Validation
- ISA/IEA segment presence and structure
- GS/GE functional group pairing
- ST/SE transaction set pairing
- Control number matching
- Segment count validation

### Format Validation
- Date format (CCYYMMDD)
- NPI format and Luhn check
- ZIP code format
- Monetary amount format
- Element length validation

### Business Rules
- Required entity presence (submitter, billing provider, payer)
- Charge total consistency
- Service line validation
- Diagnosis code format
- Procedure code validation

### Code Set Validation
- Place of service codes
- Claim adjustment reason codes
- Entity identifier codes
- Relationship codes
- Coverage level codes

---

## Code Sets

ValidEDI includes comprehensive code sets:

- **200+ Adjustment Reason Codes** (CARC)
- **50+ Segment Descriptions**
- **30+ Entity Codes**
- **35+ Date Qualifiers**
- **13 Coverage Level Codes**
- **10 Relationship Codes**
- **8 Claim Status Codes**
- **Common ICD-10 Codes**
- **Common CPT Codes**

All code sets are in YAML files and can be extended.

---

## LLM Integration

ValidEDI's LLM integration is **provider-agnostic** - works with ANY LLM:

### Supported Providers (Examples Included)

1. **OpenAI** (GPT-4, GPT-3.5)
2. **Groq** (Llama 3.1, Mixtral, Gemma) - Free tier available
3. **AWS Bedrock** (Claude, Llama)
4. **Google Gemini** - Free tier available
5. **Anthropic Claude**
6. **Azure OpenAI**
7. **Local Models** (Ollama, LM Studio, etc.)
8. **Custom Implementations**

### Features

- Plain-English explanations of EDI files
- Interactive Q&A about your data
- Validation error explanations with fix instructions
- Rule-based fallback (works without LLM)
- Zero dependencies (bring your own LLM)

---

## Requirements

- Python 3.8+
- pydantic >= 2.0
- pyyaml >= 6.0

### Optional (for LLM features)
- openai (for OpenAI)
- groq (for Groq)
- anthropic (for Anthropic)
- google-generativeai (for Gemini)
- boto3 (for AWS Bedrock)

---

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Areas for Contribution

- Additional transaction types (270/271, 276/277, 278, 997, 999)
- More validation rules
- Additional code sets
- Performance optimizations
- Documentation improvements
- Bug fixes

---

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

## Support

- **Documentation**: [docs/](docs/)
- **Examples**: [examples/](examples/)
- **Issues**: [GitHub Issues](https://github.com/yourusername/validedi/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/validedi/discussions)

---

## Roadmap

### v0.2.0 (Planned)
- [ ] Additional transaction types (270/271, 276/277)
- [ ] Performance optimizations
- [ ] Streaming parser for large files
- [ ] Web UI for validation

### v0.3.0 (Planned)
- [ ] Real-time validation API
- [ ] Batch processing optimizations
- [ ] Custom rule DSL
- [ ] Report generation

---

## Acknowledgments

- Built with inspiration from Shaunak's X12-EDI-PARSER
- Validation rules based on X12 5010 implementation guides
- Code sets from HIPAA standards

---

## Quick Links

- [Quick Start Guide](QUICKSTART.md)
- [Architecture Deep Dive](docs/ARCHITECTURE.md)
- [LLM Integration Guide](docs/LLM_GUIDE.md)
- [API Reference](docs/API_REFERENCE.md)
- [Examples](examples/)

---

**Made with ❤️ for the healthcare tech community**
