Skip to main content

Mainframe Modernization Toolkit

Deterministic tools and agent instructions for migrating a JCL-bounded COBOL workload to Python or PySpark.

The toolkit discovers source relationships, validates configuration and record layouts, extracts SQL and business rules, generates typed boundaries, compiles validated relational IR to PySpark, and compares final outputs with an authoritative Golden Dataset. It does not invent missing source semantics.

Install

Python 3.10 or newer is required.

python -m pip install mainframe-modernization-toolkit
mainframe-toolkit --version

Optional runtime dependencies:

python -m pip install "mainframe-modernization-toolkit[pyspark]"
python -m pip install "mainframe-modernization-toolkit[aws]"

Initialize A Workspace

mainframe-toolkit workspace init . --target vscode
mainframe-toolkit workspace init . --target claude
mainframe-toolkit workspace init . --target all

The initializer adds mainframe-migration.json, JSON schemas, and the selected agent integration without overwriting existing files. Configure source directories, encoding, extensions, known external dependencies, transport profiles, environment facts, and targetCapabilities in mainframe-migration.json.

For Claude Code, verify the project MCP server with claude mcp list or /mcp.

Migration Workflow

A migration starts from one JCL. A compact campaign inventories the job, then processes one program at a time so large jobs do not produce one huge preflight response.

mainframe-toolkit run migration_campaign -- init . --jcl MYJOB --format json
mainframe-toolkit run migration_campaign -- next . --jcl MYJOB --worker local --format json

For each selected program:

  1. Resolve dependencies, callers, copybooks, impact, and blockers.
  2. Generate canonical record contracts and readers.
  3. Extract SQL and business rules.
  4. Generate one program capsule containing machine-readable I/O and partial IR.
  5. Implement cohesive business logic and focused tests.
  6. Validate relational IR and compile PySpark when appropriate.
  7. Mark the program complete and claim the next one.

After all programs are implemented, compose the JCL pipeline and compare its final output with an authoritative Golden Dataset.

mainframe-toolkit validate-golden . --manifest validation/job-output.json --format json

Intermediate program outputs do not require Golden files when the migrated job passes DataFrames in process. Validate those boundaries with explicit contracts and focused tests.

Core Commands

Command Purpose
migration_preflight Validate sources, references, environment, scope, and target capabilities.
migration_campaign Track compact program-at-a-time progress for one JCL.
dependency_graph Build CALL, COPY, and EXEC relationships.
impact_analysis Calculate transitive impact.
dead_code_finder Find unreferenced migration candidates.
jcl_flow_extractor Extract JCL flow and generate a local runner.
migration_complexity_report Order programs by deterministic risk.
copybook_to_contract Generate canonical record contracts.
copybook_to_dataclass Generate Python boundary models.
generate_copybook_fixtures Generate ingestion-only test records.
generate_file_readers Generate contract-based readers.
sql_extractor Extract SQL and host variables.
business_rule_extractor Extract conditional rules with source locations.
characterization_test_scaffolder Generate a starting characterization test.
generate_program_capsule Generate a program manifest, contracts, and partial IR.
validate_relational_ir Validate typed relational IR.
ir_to_pyspark Compile executable IR to PySpark.
golden_validate Compare authoritative expected and actual CSV files.

Run any command through the stable entry point:

mainframe-toolkit run <command> -- <arguments>

AWS Glue And Local PySpark

Use the aws-glue-pyspark starter profile when creating a new configuration:

mainframe-toolkit run migration_preflight -- . --write-template --profile aws-glue-pyspark

Keep transformations in transform_frames(). Production wrappers can use Glue Catalog, S3, and Iceberg descriptors; local runners can load semicolon-delimited CSV files with explicit schemas and invoke the same transformations.

The toolkit does not provision AWS resources. IAM, Lake Formation, buckets, Glue jobs, Catalog tables, bookmarks, connectors, and Iceberg configuration belong in deployment infrastructure.

Safety Boundaries

  • Missing copybooks, PROCs, conflicting sources, parse failures, and unsafe layouts block the affected migration.
  • Unknown external programs remain explicit adapter TODOs.
  • Synthetic fixtures validate ingestion, not business equivalence.
  • Only mainframe output or a verified equivalent implementation is an authoritative Golden Dataset.
  • Generated relational IR with TODOs is non-executable.

See docs/JCL-MIGRATION-GUIDE.md for the concise end-to-end procedure.

Metadata

Release files for mainframe-modernization-toolkit 0.1.19

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mainframe-modernization-toolkit 0.1.19
File Size Uploaded Provenance Actions
mainframe_modernization_toolkit-0.1.19.tar.gz 5.9 MB Without provenance Details for mainframe_modernization_toolkit-0.1.19.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mainframe-modernization-toolkit 0.1.19
File Interpreter ABI Platform Actions
mainframe_modernization_toolkit-0.1.19-py3-none-any.whl Python 3 none any Details for mainframe_modernization_toolkit-0.1.19-py3-none-any.whl

Total release size: 11.8 MB

Release files / mainframe_modernization_toolkit-0.1.19.tar.gz

Download URL mainframe_modernization_toolkit-0.1.19.tar.gz
Size 5.9 MB
Tags Source
SHA-256 checksum
How to use checksums
8134485bd9b1393ec07a3299f4c9a1700953d2ee67af6e4a4b0ca6afc1f308ed
BLAKE2b-256 checksum
How to use checksums
b7db763cecf8b2233d184c56f31d04cc6ce3f34e128008f8f3cd8a4c7e9805d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / mainframe_modernization_toolkit-0.1.19-py3-none-any.whl

Download URL mainframe_modernization_toolkit-0.1.19-py3-none-any.whl
Size 5.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c04c6d0d955f5155d4080e5202cddcfcf8c9c4b02865b6f78b576e88e3089c6a
BLAKE2b-256 checksum
How to use checksums
3cd5e59351320353a4741d11ac8f4532fd69a3febc09b3d42ab88c67539c65ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for mainframe-modernization-toolkit 0.1.19

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page