Codebase Migration & Refactor Planner (LangGraph)

An AI-powered multi-agent codebase migration assistant built with LangGraph and Streamlit that plans file-by-file refactoring tasks, performs human-in-the-loop (HITL) risk review, fans out parallel refactoring workers, and aggregates complete diffs with visual risk charts.

Features

• 🧠 Planner Agent - Analyzes a repository target and migration goal to generate an architectural strategy plus a file-by-file migration plan with risk levels (Low, Medium, High, Critical).
• 🛡️ Human-in-the-Loop Approval Gate - Pause execution via LangGraph interrupt() so engineers can inspect, review, and modify risk levels or file scopes in natural language before any code changes occur.
• 🛠️ Parallel Refactor Workers - Fan out simultaneously via LangGraph's Send() API - one worker per file in the plan - generating precise code diffs, breaking changes analysis, and recommended test cases.
• 📊 Aggregator Agent - Synthesizes all file diffs into a publication-ready Migration Guide & Report, auto-generating 1-2 data-driven matplotlib charts (embedded as base64 images).
• 🖥️ Streamlit UI - Sidebar API configuration, risk badges, interactive revision controls, markdown report rendering with embedded charts, and one-click .md download.
• ✅ Query Validation - Validates repository inputs and migration goals to block empty, unsafe, or destructive prompts before hitting LLMs.

How to Run

1. Clone the repository

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd awesome-llm-apps/advanced_ai_agents/multi_agent_apps/ai_codebase_migration_agent

2. Install dependencies

pip install -r requirements.txt

3. Run the app

streamlit run app.py

LLM Configuration: Add your key to a .env file (see .env.example) or enter it in the app sidebar:

```env

OPENAI_API_KEY=sk-your-key-here

```

Defaults to gpt-5-mini for planning and the per-file workers, and gpt-5.5 for the final report synthesis. Override with MODEL_FAST / MODEL_PRO, or point at any OpenAI-compatible provider by also setting LLM_BASE_URL.

How It Works

Repo Target + Goal → Validator → Planner (Strategy + File Tasks) → HITL Approval → Parallel Refactor Workers → Aggregator → Migration Guide & Diffs

1. Query Validator verifies that both a valid repository path/URL and a substantive migration goal are provided.
2. Planner Agent (structured output) formulates a high-level migration strategy and breaks down changes into 3–6 file migration tasks with estimated risk levels.
3. Plan Approval Gate pauses the graph using LangGraph's interrupt() API to let developers review the risk matrix, request revisions in natural language, or approve execution.
4. Parallel Refactor Workers fan out via Send() API calls - one branch per file - to produce unified diffs, before/after snippets, and test cases.
5. Aggregator Agent synthesizes all refactoring diffs into a comprehensive report, chooses chart data (not executable code), renders visual risk charts using trusted Matplotlib templates, and outlines post-migration validation steps.

Session state is persisted using LangGraph's in-memory MemorySaver, allowing execution interrupts to survive Streamlit reruns seamlessly.

Example Use Cases

• Framework & Library Upgrades - e.g. Pydantic v1 → v2 (BaseModel, @validator to Field, @field_validator), Flask 2 → 3, SQLAlchemy 1.4 → 2.0.
• Language / Syntax Conversions - e.g. Converting JavaScript files (.js) to TypeScript (.ts) with strict interfaces.
• Async & Performance Refactoring - e.g. Converting synchronous I/O and database handlers to async/await.
• Deprecation Cleanups - Replacing deprecated API patterns across multiple services safely.

Technical Details

Dependencies

• langgraph
• langgraph-checkpoint
• langchain / langchain-core / langchain-openai
• pydantic
• python-dotenv
• streamlit
• matplotlib

License

This project is part of the awesome-llm-apps collection and is available under the Apache-2.0 License.