# 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.

- Source: https://doutorai.pt/en/apps/ai-codebase-migration-agent
- Category: Agent Teams
- Difficulty: Advanced
- Models: OpenAI, Llama, DeepSeek
- Frameworks: LangChain, Ollama (local)
- Runs locally?: Yes (Ollama)
- Required keys: LLM_API_KEY, OPENAI_API_KEY
- License: Apache-2.0
- Site: Doutor AI (https://doutorai.pt/en) - AI tools for small businesses

## Full tutorial

# ⚡ 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**

   ```bash
   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**

   ```bash
   pip install -r requirements.txt
   ```

3. **Run the app**

   ```bash
   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

| Layer | Technology |
|---|---|
| Agent Graph | LangGraph (`Send()` fan-out, `interrupt()` HITL, `MemorySaver` checkpointer) |
| LLMs | Configurable (defaults: `gpt-5-mini` for fast steps, `gpt-5.5` for synthesis) |
| Charts | Validated data rendered by trusted Matplotlib templates (embedded base64 PNG data URIs) |
| UI | Streamlit |

## 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.

## Save hours every week with AI, no hassle

**Doutor AI** gives you 1,859 ready-to-copy AI prompts, by industry and in plain English - plus a complete technical library for those who want to go further. [See plans →](https://doutorai.pt/en/pricing)

---
Content by Doutor AI (https://doutorai.pt/en). When quoting, please cite the source: https://doutorai.pt/en/apps/ai-codebase-migration-agent