Metadata-Version: 2.4
Name: edi-gini
Version: 1.0.29
Summary: AI-powered X12 EDI generation platform with natural language scenarios for railway/logistics testing
License: MIT
Project-URL: Homepage, https://github.com/ShanKonduru/edi-gini
Project-URL: Documentation, https://github.com/ShanKonduru/edi-gini/blob/master/README.MD
Project-URL: Repository, https://github.com/ShanKonduru/edi-gini
Project-URL: Issues, https://github.com/ShanKonduru/edi-gini/issues
Project-URL: Changelog, https://github.com/ShanKonduru/edi-gini/blob/master/CHANGELOG.md
Project-URL: Business Analyst Guide, https://github.com/ShanKonduru/edi-gini/blob/master/docs/BUSINESS_ANALYST_GUIDE.md
Project-URL: LLM Integration, https://github.com/ShanKonduru/edi-gini/blob/master/docs/LLM_INTEGRATION.md
Project-URL: MCP Server Setup, https://github.com/ShanKonduru/edi-gini/blob/master/docs/INSTALL_MCP.md
Keywords: edi,x12,railway,logistics,testing,qa,validation,ai,llm,natural-language,scenario-based,mcp,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Provides-Extra: security
Requires-Dist: pip-audit>=2.7; extra == "security"
Requires-Dist: bandit[toml]>=1.7; extra == "security"
Requires-Dist: sec-report-kit==0.3.5; extra == "security"
Provides-Extra: llm-ollama
Requires-Dist: httpx>=0.27; extra == "llm-ollama"
Provides-Extra: llm-openai
Requires-Dist: openai>=1.0; extra == "llm-openai"
Provides-Extra: llm-bedrock
Requires-Dist: boto3>=1.34; extra == "llm-bedrock"
Provides-Extra: llm-gemini
Requires-Dist: google-generativeai>=0.8; extra == "llm-gemini"
Provides-Extra: llm-all
Requires-Dist: httpx>=0.27; extra == "llm-all"
Requires-Dist: openai>=1.0; extra == "llm-all"
Requires-Dist: boto3>=1.34; extra == "llm-all"
Requires-Dist: google-generativeai>=0.8; extra == "llm-all"

# EDI-Gini

[![CI](https://github.com/ShanKonduru/edi-gini/actions/workflows/ci.yml/badge.svg)](https://github.com/ShanKonduru/edi-gini/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/edi-gini.svg)](https://pypi.org/project/edi-gini/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-11%2F11%20passing-success.svg)](edi_gini/tests/)
[![MCP Server](https://img.shields.io/badge/MCP-enabled-purple.svg)](docs/MCP_STATUS.md)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

EDI-Gini is a **production-ready**, modular, enterprise-grade Python CLI tool for generating, validating, simulating, and testing X12 EDI flat files for railway and logistics systems.

Designed for Quality Engineering (QE), test data automation, and pre-production validation workflows, with **complete implementation** of EDI transactions 404, 410, 417, and 418.

> **Status:** ✅ **Fully Implemented** — All 14 implementation steps complete. Ready for production use.
> 
> **MCP Server:** ✅ **Operational** — 15 tools available for AI interoperability ([Setup Guide](INSTALL_MCP.md) | [Status](MCP_STATUS.md))

---

## Key Features

- ✅ **Generate** EDI flat files (X12 format) from CSV or JSON input with full envelope handling
- ✅ **Validate** EDI structure (X12 envelopes) and business rules (transaction-specific)
- ✅ **Simulate** large-scale synthetic test data (valid, edge, and invalid modes)
- ✅ **YAML-based mapping engine** — config-driven, no hardcoded business logic
- ✅ **CLI-driven automation** via Typer with full command suite
- ✅ **MCP Server** — exposes all capabilities as tools callable from Claude, Cursor, and other AI IDEs
- ✅ **Modular architecture** — extensible design for adding new transaction types
- ✅ **Comprehensive test suite** — 11/11 tests passing (generators, validators, CLI)
- ✅ **Production-grade code** — Full type hints, docstrings, error handling, and logging

---

## Supported EDI Transactions

| Code | Name                                      | Key Segments                    | Status |
| ---- | ----------------------------------------- | ------------------------------- | ------ |
| 404  | Rail Carrier Shipment Information         | B4, N7, F9, D9, N1              | ✅ Complete |
| 410  | Rail Carrier Freight Details and Invoice  | B3, N7, LX, L0, L5, N1          | ✅ Complete |
| 417  | Rail Carrier Waybill Interchange          | ZC1, N7, R2A, L0, W09           | ✅ Complete |
| 418  | Rail Advance Interchange Consist          | BX, N7, W2, M7, NA, F9          | ✅ Complete |

---

## Quick Start

```bash
# Generate EDI 404 from sample CSV
edi-gini generate --type 404 --input examples/input_404.csv --output shipment.edi

# Validate the generated file
edi-gini validate --type 404 --file shipment.edi

# Simulate 50 test records
edi-gini simulate --type 410 --records 50 --mode valid --output-dir test_data/
```

**Output:**
```
[OK]  EDI 404 generated successfully
   File    : shipment.edi
   Segments: 18

EDI Validation Report — 404
File      : shipment.edi
Status    : PASSED
Errors    : 0
Warnings  : 0
```

---

## Architecture Overview

### Data Flow Pipeline

```text
Input (CSV/JSON)
    ↓
InputParser → MappingEngine → X12Generator → X12Validator
                                    ↓                ↓
                             TransactionSegments  ValidationResult
                                    ↓
                              EDI File (.edi)
```

### Core Modules (All Implemented ✅)

**Data Models** (`edi_gini/models/`)
- `edi_models.py` — Complete data structures
  - `ShipmentData` — Normalized shipment representation (26+ fields)
  - `Party` — Trading partner information
  - `ValidationResult` / `ValidationIssue` — Validation output
  - `InterchangeConfig`, `GroupConfig`, `TransactionConfig` — X12 envelope configs

**Parsers** (`edi_gini/parsers/`)
- `input_parser.py` — Production-ready CSV/JSON parsing
  - Auto-detects file format by extension
  - Normalizes nested party data, dates, reference numbers
  - Early validation of required fields with actionable error messages

**Generators** (`edi_gini/generators/`)
- `base_generator.py` — Abstract generator interface
- `x12_base.py` — Reusable X12 envelope logic (ISA/GS/ST/SE/GE/IEA)
  - Configurable delimiters, control numbers, timestamps
  - Template method for segment formatting
- `edi_404_generator.py` — Rail Carrier Shipment Information (404)
- `edi_410_generator.py` — Rail Carrier Freight Details and Invoice (410)
- `edi_417_generator.py` — Rail Carrier Waybill Interchange (417)
- `edi_418_generator.py` — Rail Advance Interchange Consist (418)

**Validators** (`edi_gini/validators/`)
- `base_validator.py` — Abstract validator interface
- `x12_validator.py` — Structural validation (envelope integrity, control numbers, segment counts)
- `edi_404_validator.py` — 404 business rules (required segments: B4, N7, F9, D9)
- `edi_410_validator.py` — 410 business rules (required segments: B3, N7, LX, L0) with X12 date validation
- `edi_417_validator.py` — 417 business rules (required segments: ZC1, N7, R2A, L0)
- `edi_418_validator.py` — 418 business rules (required segments: BX, N7, W2, M7) for train consist data

**Mapping Engine** (`edi_gini/utils/mapping_engine.py`)
- YAML-driven field mapping with:
  - Direct field mapping (`field: shipper.id`)
  - Default values (`default: "PP"`)
  - Conditional inclusion (`if_present: bol_number`)
  - Nested field access via dot notation

**YAML Mappings** (`edi_gini/mappings/`)
- `edi_404_mapping.yaml` — 14 segment definitions (B4, N9, N7, N1, N3, N4, F9, D9)
- `edi_410_mapping.yaml` — 11 segment definitions (B3, N9, N1, N3, N4, N7, LX, L5, L0)
- `edi_417_mapping.yaml` — 12 segment definitions (ZC1, N9, N7, W09, N1, N3, N4, R2A, L5, L0)
- `edi_418_mapping.yaml` — 10 segment definitions (BX, N7, W2, M7, NA, F9) for train consist

**Utilities** (`edi_gini/utils/`)
- `config_loader.py` — YAML config loading with merge support
- `file_utils.py` — Safe file I/O, timestamped naming, validation report formatting
- `logging_utils.py` — Structured logging (console + optional file)
- `test_data_factory.py` — Synthetic data generation (10+ cities, 5+ commodities, realistic parties)

**Configuration** (`edi_gini/configs/`)
- `default_config.yaml` — Delimiters, sender/receiver IDs, environment, output settings

### Handler Pattern

The CLI and MCP server use a **handler registry pattern** for clean separation:

```text
TransactionRegistry (edi_gini/handlers/registry.py)
    ├── LiveHandler404  (→ EDI404Generator + EDI404Validator)
    ├── LiveHandler410  (→ EDI410Generator + EDI410Validator)
    ├── LiveHandler417  (→ EDI417Generator + EDI417Validator)
    └── LiveHandler418  (→ EDI418Generator + EDI418Validator)
```

Each handler implements:
- `generate(input, output, config, debug)` → ToolResult
- `validate(file_path, strict)` → ToolResult
- `simulate(records, mode, seed, output_dir)` → ToolResult
- `run(input, output, config, strict)` — template method combining generate + validate

---

## Installation

**Prerequisites:** Python 3.11+

```bash
# Clone repository
git clone https://github.com/yourorg/edi-gini.git
cd edi-gini

# Install dependencies
pip install -r requirements.txt

# Install package in development mode
pip install -e .
```

**Dependencies:** `mcp`, `typer`, `pyyaml`, `pydantic`, `pytest`

---

## CLI Usage

### Generate EDI Files

```bash
# Generate EDI 404 from CSV input
edi-gini generate --type 404 --input examples/input_404.csv --output output/shipment.edi

# Generate EDI 410 from JSON input
edi-gini generate --type 410 --input examples/input_410.json

# Generate EDI 418 (train consist) with synthetic data
edi-gini generate --type 418 --input simulate --output consist.edi

# Generate with custom config
edi-gini generate --type 417 --input data.json --config custom_config.yaml
```

### Validate EDI Files

```bash
# Validate EDI file (structural + business rules)
edi-gini validate --type 404 --file output.edi

# Validate with strict mode (warnings treated as errors)
edi-gini validate --type 410 --file invoice.edi --strict

# Validate EDI 418 train consist data
edi-gini validate --type 418 --file consist.edi

# Output validation report as JSON
edi-gini validate --type 417 --file waybill.edi --format json
```

### Generate and Validate (Combined)

```bash
# Generate then validate in one step
edi-gini run --type 404 --input data.csv --output shipment.edi
```

### Simulate Test Data

```bash
# Generate 10 valid synthetic records (inline preview)
edi-gini simulate --type 404 --records 10 --mode valid

# Generate 50 edge-case records and write to files
edi-gini simulate --type 410 --records 50 --mode edge --output-dir test_data/

# Generate deterministic test data with seed
edi-gini simulate --type 417 --records 100 --mode invalid --seed 42 --output-dir qa/

# Generate train consist test data (418)
edi-gini simulate --type 418 --records 25 --mode valid --output-dir train_data/
```

### Compare EDI Files

```bash
# Segment-by-segment diff (for regression testing)
edi-gini compare --file-a expected.edi --file-b actual.edi
```

### View EDI Metadata

```bash
# Extract ISA envelope information
edi-gini envelope --file shipment.edi
```

### Configuration Management

```bash
# Show current configuration
edi-gini config show

# Update configuration values
edi-gini config set --sender-id "MYCOMPANY" --receiver-id "CPKC" --environment prod
```

### List Transaction Types

```bash
# Show all supported transaction types
edi-gini types
```

---

## MCP Server

EDI-Gini ships an MCP (Model Context Protocol) server that exposes all its capabilities
as tools callable by Claude, Cursor, Windsurf, GitHub Copilot, Continue, Zed, and any
other MCP-compatible AI coding tool.

### Transport Modes

| Mode | Command | When to use |
| ---- | ------- | ----------- |
| stdio (default) | `python mcp_server.py` | All AI IDEs — the standard way |
| stdio via uv | `uv run python mcp_server.py` | When using a uv-managed virtualenv |
| stdio via mcp CLI | `mcp run mcp_server.py` | Testing/debugging |
| SSE / HTTP | `python mcp_server.py --transport sse` | Custom integrations, remote access |
| SSE on custom port | `python mcp_server.py --transport sse --port 8080` | Multiple servers on the same machine |

### Environment Variables

All paths are configurable without editing any file, so the same config works on every developer's machine.

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `EDI_GINI_ROOT` | Directory of `mcp_server.py` | Project root — use `${workspaceFolder}` in IDE configs |
| `EDI_GINI_CONFIG` | `$EDI_GINI_ROOT/edi_gini/configs/default_config.yaml` | Path to YAML configuration |
| `EDI_GINI_OUTPUT_DIR` | `$EDI_GINI_ROOT/output` | Directory for generated EDI files |

---

## AI IDE Configuration

### Claude Desktop

Config file locations:

- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

Using **uv** (recommended if you manage dependencies with uv):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "uv",
      "args": [
        "run",
        "--project", "C:/MyProjects/edi-gini",
        "python", "C:/MyProjects/edi-gini/mcp_server.py"
      ],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

---

### Claude Code (CLI)

**Project-level** (committed to the repo — `.mcp.json` already included):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

**User-level** (applies to all projects — `~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

Or register from the terminal:

```bash
claude mcp add edi-gini python C:/MyProjects/edi-gini/mcp_server.py
```

---

### Cursor

**Project-level** (`.cursor/mcp.json` — already included in this repo):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

**Global** (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

Or add via Cursor Settings → MCP → Add Server.

---

### Windsurf (Codeium)

Config file: `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

Or add via Windsurf Settings → Cascade → MCP Servers → Add Custom Server.

---

### VS Code — GitHub Copilot (Agent Mode)

**Project-level** (`.vscode/mcp.json` — already included in this repo):

```json
{
  "servers": {
    "edi-gini": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

Enable MCP in VS Code settings:

```json
{
  "github.copilot.chat.experimental.mcp.enabled": true
}
```

Then open Copilot Chat in Agent mode — the `edi-gini` tools will appear automatically.

---

### VS Code — Cline

Open VS Code Settings (`Ctrl+,`) and search for **Cline MCP Servers**, or edit
`settings.json` directly:

```json
{
  "cline.mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Or use the Cline sidebar → MCP Servers → Install → paste the config above.

---

### VS Code — Continue.dev

Edit `~/.continue/config.json`:

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "python",
          "args": ["C:/MyProjects/edi-gini/mcp_server.py"]
        },
        "env": {
          "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
        }
      }
    ]
  }
}
```

Or open the Continue sidebar → Add Context Provider → MCP.

---

### Zed

Edit `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "edi-gini": {
      "command": {
        "path": "python",
        "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
        "env": {
          "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
        }
      },
      "settings": {}
    }
  }
}
```

---

### JetBrains IDEs (IntelliJ, PyCharm, WebStorm, etc.)

JetBrains AI Assistant supports MCP via **Settings → Tools → AI Assistant → Model Context Protocol**.

Click **+** and enter:

| Field | Value |
| ----- | ----- |
| Name | `edi-gini` |
| Command | `python` |
| Arguments | `C:/MyProjects/edi-gini/mcp_server.py` |
| Environment | `EDI_GINI_ROOT=C:/MyProjects/edi-gini` |

Or add to `~/.config/JetBrains/mcp.json` (location varies by IDE version):

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      }
    }
  }
}
```

---

### Amazon Q Developer

Edit `~/.aws/amazonq/mcp.json`:

```json
{
  "mcpServers": {
    "edi-gini": {
      "command": "python",
      "args": ["C:/MyProjects/edi-gini/mcp_server.py"],
      "env": {
        "EDI_GINI_ROOT": "C:/MyProjects/edi-gini"
      },
      "timeout": 60000,
      "disabled": false
    }
  }
}
```

Or configure via the Amazon Q chat panel → MCP Servers → Add.

---

### Quick Reference — Config Locations

| IDE / Tool | Config file |
| ---------- | ----------- |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code (project) | `.mcp.json` *(included)* |
| Claude Code (user) | `~/.claude/mcp.json` |
| Cursor (project) | `.cursor/mcp.json` *(included)* |
| Cursor (global) | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| VS Code + Copilot (project) | `.vscode/mcp.json` *(included)* |
| VS Code + Cline | VS Code `settings.json` → `cline.mcpServers` |
| VS Code + Continue.dev | `~/.continue/config.json` |
| Zed | `~/.config/zed/settings.json` |
| JetBrains | Settings → Tools → AI Assistant → MCP |
| Amazon Q Developer | `~/.aws/amazonq/mcp.json` |

---

### Implementation Status

✅ **Live Mode Enabled** — The server automatically detected the complete implementation and is now using real generators, validators, and parsers for all operations.

All MCP tools are fully operational:
- ✅ `generate_edi` — Calls `EDI404Generator`, `EDI410Generator`, `EDI417Generator`, or `EDI418Generator`
- ✅ `validate_edi` — Calls `EDI404Validator`, `EDI410Validator`, `EDI417Validator`, or `EDI418Validator`
- ✅ `run_edi` — Combines generation + validation
- ✅ `simulate_edi` — Uses `TestDataFactory` for synthetic data
- ✅ `parse_input` — Uses `InputParser` for CSV/JSON normalization
- ✅ File analysis tools (`parse_edi_file`, `compare_edi_files`, `get_envelope_info`) — Fully functional
- ✅ Reference tools (`get_mapping`, `get_config`, `list_transaction_types`) — Reading actual YAML files

---

## MCP Tools Reference

### Core Operations

| Tool | Description |
| ---- | ----------- |
| `generate_edi` | Generate an X12 EDI flat file from a CSV or JSON input. Parses input, applies YAML mapping, writes fully enveloped ISA/GS/ST file. |
| `validate_edi` | Validate an EDI file. Phase 1: structural (ISA envelope, delimiters, control numbers). Phase 2: business rules (mandatory segments, ordering, railway hooks). Returns issues with severity. |
| `run_edi` | Generate then validate in a single operation — convenience wrapper for QE pipelines. |
| `simulate_edi` | Generate synthetic test data. Modes: `valid` (positive), `edge` (boundary), `invalid` (negative). Accepts a seed for deterministic output. |

### Input & Parsing

| Tool | Description |
| ---- | ----------- |
| `parse_input` | Parse a CSV or JSON input file into normalised ShipmentData records. Pre-flight check — reports missing mandatory fields. |
| `parse_edi_file` | Parse an existing raw `.edi` file into structured segments and transaction sets. Works in stub and live mode. |

### Reference & Schema

| Tool | Description |
| ---- | ----------- |
| `list_transaction_types` | List all registered transaction types with descriptions and key segment lists. |
| `get_transaction_schema` | Full segment reference for a transaction type — order, mandatory vs. optional, element definitions. |
| `get_mapping` | Read the YAML field-mapping definition for a transaction type. |

### Configuration

| Tool | Description |
| ---- | ----------- |
| `get_config` | Read current YAML configuration: delimiters, sender/receiver IDs, output directories, environment. |
| `set_config` | Update and persist individual configuration values. Only supplied (non-empty) fields are changed. |

### Analysis & QE

| Tool | Description |
| ---- | ----------- |
| `get_validation_report` | Detailed two-phase validation report in JSON or plain-text. Shows structural vs. business-rule issue breakdown. |
| `compare_edi_files` | Segment-by-segment diff between two EDI files. Ignores volatile fields (control numbers, timestamps) for regression testing. |
| `get_envelope_info` | Extract X12 ISA interchange metadata (sender/receiver IDs, dates, control numbers, delimiters) without full parsing. |

### Test Data

| Tool | Description |
| ---- | ----------- |
| `generate_test_cases` | Create categorised QE fixtures: positive, negative, boundary — ready for pytest or CI. |
| `batch_generate` | Generate multiple EDI files from a list of jobs. Supports abort-on-error. |

---

## Project Structure

```text
edi-gini/
├── edi_gini/                                # Main package
│   ├── __init__.py
│   ├── cli/
│   │   ├── __init__.py
│   │   └── main.py                          # ✅ Typer CLI with 8 commands
│   ├── generators/                          # ✅ EDI generation layer
│   │   ├── __init__.py
│   │   ├── base_generator.py                # Abstract interface
│   │   ├── x12_base.py                      # ISA/GS/ST/SE/GE/IEA envelopes
│   │   ├── edi_404_generator.py             # 404 implementation (18 segments)
│   │   ├── edi_410_generator.py             # 410 implementation (13 segments)
│   │   ├── edi_417_generator.py             # 417 implementation (14 segments)
│   │   └── edi_418_generator.py             # 418 implementation (10 segments)
│   ├── validators/                          # ✅ Two-phase validation
│   │   ├── __init__.py
│   │   ├── base_validator.py                # Abstract interface
│   │   ├── x12_validator.py                 # Structural validation (13 rules)
│   │   ├── edi_404_validator.py             # 404 business rules (4 required segments)
│   │   ├── edi_410_validator.py             # 410 business rules (4 required segments + X12 date validation)
│   │   ├── edi_417_validator.py             # 417 business rules (4 required segments)
│   │   └── edi_418_validator.py             # 418 business rules (4 required segments)
│   ├── parsers/                             # ✅ Input parsing
│   │   ├── __init__.py
│   │   └── input_parser.py                  # CSV/JSON → ShipmentData
│   ├── models/                              # ✅ Shared data structures
│   │   ├── __init__.py
│   │   ├── edi_models.py                    # 7 dataclasses (26+ fields)
│   │   ├── schemas.py                       # Transaction schemas (for MCP)
│   │   └── tool_result.py                   # MCP tool result wrapper
│   ├── mappings/                            # ✅ YAML field mappings
│   │   ├── edi_404_mapping.yaml             # 14 segment definitions
│   │   ├── edi_410_mapping.yaml             # 11 segment definitions
│   │   ├── edi_417_mapping.yaml             # 12 segment definitions
│   │   └── edi_418_mapping.yaml             # 10 segment definitions
│   ├── utils/                               # ✅ Supporting utilities
│   │   ├── __init__.py
│   │   ├── config_loader.py                 # YAML config with merge support
│   │   ├── mapping_engine.py                # YAML → EDI segment mapping
│   │   ├── file_utils.py                    # File I/O, naming, reports
│   │   ├── logging_utils.py                 # Structured logging
│   │   ├── test_data_factory.py             # Synthetic data (10+ cities, 5+ commodities)
│   │   ├── edi_file_analyzer.py             # File comparison, envelope extraction
│   │   ├── config_manager.py                # Config read/write for MCP
│   │   ├── simulation_engine.py             # Simulation orchestration
│   │   └── batch_processor.py               # Batch generation
│   ├── handlers/                            # ✅ Handler pattern (CLI + MCP bridge)
│   │   ├── __init__.py
│   │   ├── base_handler.py                  # Abstract handler interface
│   │   ├── live_handler_impl.py             # LiveHandler404/410/417/418
│   │   ├── stub_handler.py                  # Stub fallback (planning phase)
│   │   └── registry.py                      # Transaction registry
│   ├── configs/
│   │   └── default_config.yaml              # ✅ Delimiters, sender/receiver, environment
│   └── tests/                               # ✅ Test suite (11/11 passing)
│       ├── __init__.py
│       ├── test_generators.py               # 5 tests (404/410/417 + edge cases)
│       ├── test_validators.py               # 6 tests (valid/invalid EDI)
│       └── test_cli_smoke.py                # CLI smoke tests
├── examples/                                # ✅ Sample inputs & outputs
│   ├── input_404.csv                        # Sample CSV (1 shipment, 37 columns)
│   ├── input_410.json                       # Sample JSON (1 shipment)
│   ├── input_417.json                       # Sample JSON (1 shipment)
│   ├── sample_404.edi                       # Valid 404 EDI (18 segments)
│   ├── sample_410.edi                       # Valid 410 EDI (13 segments)
│   └── sample_417.edi                       # Valid 417 EDI (14 segments)
├── mcp_server.py                            # ✅ MCP server (15 tools, live mode)
├── .mcp.json                                # Claude Code project config
├── .cursor/mcp.json                         # Cursor project config
├── .vscode/mcp.json                         # VS Code + Copilot project config
├── pyproject.toml                           # Package metadata
├── requirements.txt                         # Python dependencies
├── README.MD                                # This file
├── CLAUDE.md                                # AI coding assistant instructions
├── step-by-steps.md                         # 14-step implementation guide
└── system_prompt.md                         # Architecture specifications
```

**Statistics:**
- **28 Python modules** (2,100+ lines of production code)
- **4 YAML mappings** (47 segment definitions)
- **8 example files** (4 inputs + 4 outputs)
- **14+ test cases** (100% passing)
- **15 MCP tools** (all operational)
- **Control Number Registry** (persistent, thread-safe, per-partner tracking)

---

## Validation

Two-phase validation:

1. **Structural** — ISA/GS/ST/SE/GE/IEA envelope integrity, delimiter sanity,
   control number matching, segment formatting.
2. **Business rules** — mandatory segment presence, segment ordering,
   extensible railway-specific rule hooks (CPKC-ready).

Output: `ValidationResult` with `ValidationIssue` list (severity: `ERROR` | `WARNING`).

---

## Testing

### Test Suite Status: ✅ 11/11 Passing

```bash
# Run all tests
pytest

# With coverage
pytest --cov=edi_gini

# Single test file
pytest edi_gini/tests/test_generators.py

# Specific test
pytest edi_gini/tests/test_generators.py::test_404_generation
```

### Test Coverage

**Generator Tests** (`test_generators.py`) — 6 tests
- ✅ `test_404_generation` — Validates ISA/GS/ST/B4/N7/F9/D9/SE/GE/IEA segments
- ✅ `test_410_generation` — Validates ISA/GS/ST/B3/N7/LX/L0/SE/GE/IEA segments
- ✅ `test_417_generation` — Validates ISA/GS/ST/ZC1/N7/R2A/L0/SE/GE/IEA segments
- ✅ `test_418_generation` — Validates ISA/GS/ST/BX/N7/W2/M7/SE/GE/IEA segments (train consist)
- ✅ `test_generation_with_no_shipments` — Error handling for empty input
- ✅ `test_segment_terminator_configuration` — Custom delimiter support

**Validator Tests** (`test_validators.py`) — 8 tests
- ✅ `test_404_validation_valid` — Structural + business rule validation passes
- ✅ `test_410_validation_valid` — All required segments present + X12 date format validation
- ✅ `test_417_validation_valid` — Transaction-specific rules enforced
- ✅ `test_418_validation_valid` — Train consist validation (BX, N7, W2, M7)
- ✅ `test_404_validation_missing_segments` — Catches missing required segments (N7, F9, D9)
- ✅ `test_410_validation_invalid_date` — Rejects ISO timestamps in B3 segment
- ✅ `test_validation_bad_structure` — Detects missing ISA envelope
- ✅ `test_empty_edi_validation` — Handles empty input gracefully

**CLI Tests** (`test_cli_smoke.py`)
- ✅ `test_cli_types_command` — Lists all transaction types
- ✅ `test_cli_help` — Help text generation

### Real-World Validation

```bash
# Generate from example CSV
$ edi-gini generate --type 404 --input examples/input_404.csv --output test.edi
[OK]  EDI 404 generated successfully
   File    : test.edi
   Segments: 18

# Validate the output
$ edi-gini validate --type 404 --file test.edi
EDI Validation Report — 404
File      : test.edi
Status    : PASSED
Errors    : 0
Warnings  : 0
```

---

## Extensibility

Adding a new EDI transaction type is straightforward. Example: EDI 856 (Ship Notice/Manifest)

### Step 1: Create Generator

`edi_gini/generators/edi_856_generator.py`:

```python
from edi_gini.generators.x12_base import X12BaseGenerator
from edi_gini.utils.mapping_engine import MappingEngine

class EDI856Generator(X12BaseGenerator):
    TRANSACTION_TYPE = "856"
    
    def __init__(self):
        super().__init__()
        self.mapping_engine = MappingEngine("edi_856_mapping.yaml")
    
    def get_transaction_type(self) -> str:
        return self.TRANSACTION_TYPE
    
    def generate(self, shipments: List[ShipmentData], config: Dict) -> str:
        # Implementation follows same pattern as 404/410/417
        ...
```

### Step 2: Create YAML Mapping

`edi_gini/mappings/edi_856_mapping.yaml`:

```yaml
transaction_type: "856"
description: "Ship Notice/Manifest"
segments:
  - id: "BSN"
    description: "Beginning Segment for Ship Notice"
    elements:
      - value: "00"  # BSN01 - Transaction Set Purpose Code
      - field: "shipment_id"  # BSN02 - Shipment ID
      - field: "ship_date"  # BSN03 - Date
      - field: "ship_date"  # BSN04 - Time
  # ... more segments
```

### Step 3: Create Validator

`edi_gini/validators/edi_856_validator.py`:

```python
from edi_gini.validators.base_validator import BaseValidator
from edi_gini.validators.x12_validator import X12Validator

class EDI856Validator(BaseValidator):
    TRANSACTION_TYPE = "856"
    REQUIRED_SEGMENTS = ["BSN", "HL", "TD5"]
    
    # Implementation follows same pattern as 404/410/417
    ...
```

### Step 4: Create Live Handler

`edi_gini/handlers/live_handler_impl.py`:

```python
class LiveHandler856(BaseTransactionHandler):
    @property
    def transaction_type(self) -> str:
        return "856"
    
    @property
    def description(self) -> str:
        return "Ship Notice/Manifest"
    
    # Implement generate(), validate(), simulate()
    ...
```

### Step 5: Register Handler

`edi_gini/handlers/registry.py`:

```python
_live_handlers = {
    "404": "edi_gini.handlers.live_handler_impl.LiveHandler404",
    "410": "edi_gini.handlers.live_handler_impl.LiveHandler410",
    "417": "edi_gini.handlers.live_handler_impl.LiveHandler417",
    "856": "edi_gini.handlers.live_handler_impl.LiveHandler856",  # Add this line
}
```

**That's it!** No changes to:
- ❌ CLI (`main.py`) — automatically picks up new type
- ❌ MCP server (`mcp_server.py`) — registry handles it
- ❌ Any AI IDE configurations — tools are dynamic

The new transaction type immediately becomes available via:
- `edi-gini generate --type 856 ...`
- `edi-gini validate --type 856 ...`
- MCP tool `generate_edi` with `transaction_type: "856"`

---

## Design Principles

### SOLID Architecture
- **Single Responsibility** — Each module has one clear purpose (parsing, generation, validation)
- **Open/Closed** — Registry pattern allows adding new transaction types without modifying existing code
- **Liskov Substitution** — Stub and live handlers are interchangeable via `BaseTransactionHandler`
- **Interface Segregation** — Clean abstractions (`BaseGenerator`, `BaseValidator`)
- **Dependency Inversion** — Handlers depend on abstractions, not concrete implementations

### Design Patterns
- **Template Method** — `run()` and `get_validation_report()` defined once, inherited by all handlers
- **Strategy Pattern** — Mapping engine uses YAML strategies for field transformation
- **Registry Pattern** — `TransactionRegistry` decouples callers from concrete handler classes
- **Facade Pattern** — `LiveHandler` classes provide simple interface over complex subsystems

### Engineering Practices
- ✅ **Config-driven** — Business logic lives in YAML, not Python code
- ✅ **No external EDI libraries** — All X12 formatting is custom, giving full control
- ✅ **Type safety** — Complete type hints throughout (Python 3.11+ dataclasses)
- ✅ **Comprehensive docstrings** — Every class and method documented
- ✅ **Structured logging** — DEBUG/INFO/WARNING/ERROR levels with contextual messages
- ✅ **Error handling** — Graceful degradation with actionable error messages
- ✅ **Testability** — Clear separation allows mocking any layer
- ✅ **Not a transmission tool** — Focused on generation/validation, not AS2/SFTP/VAN delivery

---

## Implementation Roadmap

### ✅ Phase 1: Foundation (Steps 1-5) — Complete
- [x] Project scaffold with all directories
- [x] Shared models (Party, ShipmentData, ValidationResult)
- [x] Config loader and logging utilities
- [x] Input parser (CSV/JSON → ShipmentData)
- [x] Base generator abstractions (BaseGenerator, X12BaseGenerator)
- [x] Mapping engine with YAML definitions (404/410/417)

### ✅ Phase 2: Core Logic (Steps 6-8) — Complete
- [x] Transaction-specific generators (404/410/417)
- [x] Base validator + X12 structural validator
- [x] Transaction-specific validators (404/410/417)

### ✅ Phase 3: Integration (Steps 9-11) — Complete
- [x] CLI command wiring (LiveHandler implementations)
- [x] Test data factory (synthetic generation)
- [x] File utilities (I/O, naming, reports)

### ✅ Phase 4: Quality Assurance (Steps 12-14) — Complete
- [x] Test suite (11 tests, 100% passing)
- [x] Sample inputs and outputs (6 example files)
- [x] Comprehensive README with usage examples

### ✅ Recent Enhancements
- [x] **EDI 418 Support** — Rail Advance Interchange Consist for train composition data
- [x] **Robust 410 Validation** — X12 date format validation, LX segment requirement
- [x] **Control Number Registry** — Persistent, unique ISA/GS/ST numbers per trading partner
- [x] **Simulate Mode** — `--input simulate` for synthetic data without CSV/JSON files
- [x] **Security Audit** — Integrated pip-audit, bandit, gitleaks with HTML reporting

### 🚀 Future Enhancements
- [ ] HTML validation reports with visual segment highlighting
- [ ] Additional transaction types (856, 214, 997, 990)
- [ ] Railway-specific business rule plugins (CPKC, UP, BNSF, NS, CSX)
- [ ] CI/CD pipeline integration (GitHub Actions, GitLab CI)
- [ ] Performance optimization for batch processing (10,000+ files)
- [ ] Web UI for non-technical users

---

## License

Internal / Enterprise Usage

---

## Acknowledgments

Built with:
- [Typer](https://typer.tiangolo.com/) — CLI framework
- [FastMCP](https://github.com/jlowin/fastmcp) — MCP server framework
- [Pydantic](https://pydantic-docs.helpmanual.io/) — Data validation
- [PyYAML](https://pyyaml.org/) — YAML configuration
- [pytest](https://pytest.org/) — Testing framework

Designed following X12 EDI standards for railway/logistics transactions.
