README.md

Java Migration Agent

• 1. Overview
• 2. MigrationBench Datasets
• 3. Installation
  • 3.1 Prerequisites
  • 3.2 Install Package
• 4. Usage
  • 4.1 Agent Types
  • 4.2 Running Migration
  • 4.3 Command Line Options
• 5. Citation

1. Overview

Java Migration Agent is a library for automated code migration from Java 8 to Java 17 using LLM-based agents built on the Strands Agents framework.

It provides multiple agent strategies for migration:

1. Baseline: Direct LLM-based migration
2. PE (Prompt Engineering) (Baseline + PE): Baseline with enhanced prompts for dependency updates
3. RAG (Baseline + PE + RAG): Uses retrieval-augmented generation for dependency version lookup
4. Hybrid (Seed change, followed by baseline + PE): Pre-processes dependencies before LLM migration

The agent relies on the MigrationBench package for evaluation.

2. 🤗 MigrationBench Datasets

Index	Dataset	Size	Notes
1	🤗 AmazonScience/migration-bench-java-full	5,102	Each repo has a test directory or at least one test case
2	🤗 AmazonScience/migration-bench-java-selected	300	A subset of migration-bench-java-full

3. Installation

3.1 Prerequisites

Verify you have java 17 and maven 3.9.6 installed:

# java
$ java --version
openjdk 17.0.15 2025-04-15 LTS
OpenJDK Runtime Environment Corretto-17.0.15.6.1 (build 17.0.15+6-LTS)
OpenJDK 64-Bit Server VM Corretto-17.0.15.6.1 (build 17.0.15+6-LTS, mixed mode, sharing)

# maven
$ mvn --version
Apache Maven 3.9.6 (bc0240f3c744dd6b6ec2920b3cd08dcc295161ae)
Maven home: /usr/local/bin/apache-maven-3.9.6
Java version: 17.0.15, vendor: Amazon.com Inc., runtime: /usr/lib/jvm/java-17-amazon-corretto.x86_64

If you haven't done it yet, follow the instructions in MigrationBench to install Maven.

3.2 Install Package

# cd .../JavaMigration/

cd java_migration_agent/
pip install -r requirements.txt -e .

Or with uv:

# cd .../JavaMigration/

cd java_migration_agent/
uv pip install -e .

4. Usage

See the full binary script at java_migration_agent/src/java_migration_agent/main.py.

4.1 Agent Types

Agent Type	Description
baseline	Direct LLM migration with mvn clean verify
pe	Baseline with prompt engineering for dependency updates
rag	Uses dependency version lookup tool for migration
hybrid	Pre-processes pom.xml dependencies before LLM migration

4.2 Running Migration

Run batch migration on the MigrationBench dataset:

python -m java_migration_agent \
    --agent-type baseline \
    --exp-id exp-001 \
    --hf-dataset AmazonScience/migration-bench-java-selected \
    --model-id global.anthropic.claude-sonnet-4-5-20250929-v1:0 \
    --max-workers 8 \
    --output-dir ./migration_results

4.3 Command Line Options

Flag	Type	Default	Description
--agent-type	str	(required)	Agent type: baseline, pe, rag, or hybrid
--exp-id	str	(required)	Experiment identifier for organizing results
--hf-dataset	str	AmazonScience/migration-bench-java-selected	HuggingFace dataset name
--model-id	str	global.anthropic.claude-sonnet-4-5-20250929-v1:0	Bedrock model ID
--temperature	float	1.0	Model temperature
--max-messages	int	80	Maximum messages per conversation
--max-workers	int	8	Maximum parallel workers
--output-dir	str	./migration_results	Output directory for results

5. 📚 Citation

@misc{liu2025migrationbenchrepositorylevelcodemigration,
      title={MigrationBench: Repository-Level Code Migration Benchmark from Java 8},
      author={Linbo Liu and Xinle Liu and Qiang Zhou and Lin Chen and Yihan Liu and Hoan Nguyen and Behrooz Omidvar-Tehrani and Xi Shen and Jun Huan and Omer Tripp and Anoop Deoras},
      year={2025},
      eprint={2505.09569},
      archivePrefix={arXiv},
      primaryClass={cs.SE},
      url={https://arxiv.org/abs/2505.09569},
}