Module Structure

​

Package Overview

iso8583sim/
├── __init__.py                 # Package root (minimal)
├── core/                       # Core message handling
├── llm/                        # LLM-powered features
├── cli/                        # Command-line interface
├── mcp/                        # MCP server for AI assistants
├── security/                   # PIN blocks and MACs
├── web/                        # REST API (FastAPI)
└── demo.py                     # Interactive demo helpers

​

Core Module (iso8583sim.core)

​

types.py

• ISO8583Version - Protocol version enum (1987, 1993, 2003)
• FieldType - Field data type enum (NUMERIC, ALPHA, LLVAR, etc.)
• CardNetwork - Card network enum (VISA, MASTERCARD, etc.)
• MessageClass - Message class enum (AUTHORIZATION, FINANCIAL, etc.)
• MessageFunction - Message function enum (REQUEST, RESPONSE, etc.)
• FieldDefinition - Field metadata dataclass
• ISO8583Message - Message data structure
• ParseError / BuildError - Exception types

• ISO8583_FIELDS - Standard ISO 8583 field definitions (128 fields)
• NETWORK_SPECIFIC_FIELDS - Network-specific field overrides
• VERSION_SPECIFIC_FIELDS - Version-specific field overrides

• get_field_definition() - Get field definition with network/version overrides
• detect_network() - Identify card network from PAN

​

parser.py

• ISO8583Parser - Main parser class
• EMVTag - EMV tag data structure

• parse(message, network=None) - Parse raw message string
• _parse_mti() - Extract Message Type Indicator
• _parse_bitmap() - Parse primary/secondary bitmaps
• _parse_fields() - Parse individual fields

​

builder.py

• ISO8583Builder - Main builder class

• build(message) - Build raw message string
• _format_field_value() - Format field with padding
• _build_bitmap() - Generate bitmap from fields
• _build_field() - Build field with length prefix

​

validator.py

• ISO8583Validator - Main validator class

• validate_message(message) - Full message validation
• validate_field(field_number, value, field_def) - Single field validation
• _validate_pan_luhn() - PAN Luhn checksum validation
• _validate_visa_specific() - VISA-specific rules
• _validate_mastercard_specific() - Mastercard-specific rules

​

emv.py

• parse_emv_data(data) - Parse Field 55 TLV data
• build_emv_data(tags) - Build Field 55 from tags
• format_emv_tag() - Format EMV tag for display

​

codes.py

• RESPONSE_CODES - Response codes (field 39) and meanings
• PROCESSING_CODES - Transaction types (first two digits of field 3)
• NETWORK_MANAGEMENT_CODES - Network management codes (field 70)
• CURRENCY_CODES - Common ISO 4217 codes with minor unit exponents

• detect_network_from_pan(pan) - Detect the card network from a PAN prefix

​

pool.py

• MessagePool - Reusable message object pool

• acquire() - Get message from pool
• release(message) - Return message to pool

​

LLM Module (iso8583sim.llm)

​

base.py

• LLMProvider - Abstract base class for providers
• LLMResponse - Response with metadata dataclass
• LLMError - Base LLM exception
• ProviderConfigError - Configuration error
• ProviderNotAvailableError - Missing provider/package

​

explainer.py

• MessageExplainer - Explain messages in plain English

• explain(message, verbose=False) - Explain a message
• explain_field(field_number, value) - Explain a single field
• explain_response_code(code) - Explain response code

​

generator.py

• MessageGenerator - Generate messages from descriptions

• generate(description, validate=True) - Generate message
• suggest_fields(partial_message) - Suggest missing fields

​

providers/

• __init__.py - Provider factory and auto-detection
• anthropic.py - Anthropic (Claude) provider
• openai.py - OpenAI (GPT) provider
• google.py - Google (Gemini) provider
• ollama.py - Ollama (local) provider

• get_provider(name=None) - Get provider instance
• list_available_providers() - List configured providers
• list_installed_providers() - List installed providers

​

CLI Module (iso8583sim.cli)

​

commands.py

• parse - Parse a raw ISO 8583 message
• build - Build a message from fields
• validate - Validate a message
• generate - Generate sample messages
• mcp - Run the MCP server over stdio

​

MCP Module (iso8583sim.mcp)

• create_server() - Build the server with its tools, resources and prompts
• main() - Run the server over stdio

​

Demo Module (iso8583sim.demo)

• generate_auth_request() - Generate authorization request
• generate_emv_auth() - Generate EMV authorization
• pretty_print() - Format message for display

​

Cython Extensions

• core/_parser_fast.pyx - Fast parsing functions
• core/_bitmap.pyx - Fast bitmap operations
• core/_validator_fast.pyx - Fast validation functions

try:
    from ._parser_fast import parse_mti_fast
    _USE_CYTHON = True
except ImportError:
    _USE_CYTHON = False

​

Import Patterns

​

Basic Usage

from iso8583sim.core.parser import ISO8583Parser
from iso8583sim.core.builder import ISO8583Builder
from iso8583sim.core.types import ISO8583Message

​

With Validation

from iso8583sim.core.validator import ISO8583Validator
from iso8583sim.core.types import CardNetwork

​

With LLM Features

from iso8583sim.llm import MessageExplainer, MessageGenerator
from iso8583sim.llm import get_provider, list_available_providers

​

Demo/Interactive

from iso8583sim.demo import generate_auth_request, pretty_print