# Planeador de Migração e Refatoração de Base de Código (LangGraph)

> Um assistente multiagente de migração de base de código, potenciado por IA, construído com LangGraph e Streamlit, que planeia tarefas de refatoração ficheiro a ficheiro, realiza uma revisão de riscos com intervenção humana (HITL), distribui trabalhadores de refatoração em paralelo e agrega diffs completos com gráficos visuais de risco.

- Fonte: https://doutorai.pt/apps/ai-codebase-migration-agent
- Categoria: Equipas de Agentes
- Dificuldade: Avançado
- Modelos: OpenAI, Llama, DeepSeek
- Frameworks: LangChain, Ollama (local)
- Corre local?: Sim (Ollama)
- Chaves necessárias: LLM_API_KEY, OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# ⚡ Planeador de Migração e Refatorização de Bases de Código (LangGraph)

Um assistente de migração de bases de código multiagente e baseado em IA, construído com **LangGraph** e **Streamlit**, que planeia tarefas de refatorização ficheiro a ficheiro, realiza uma revisão de riscos human-in-the-loop (HITL), lança workers de refatorização em paralelo e agrega diffs completos com gráficos visuais de risco.

## Funcionalidades

- 🧠 **Agente Planeador**: analisa o repositório alvo e o objetivo de migração para gerar uma estratégia arquitetural, além de um plano de migração ficheiro a ficheiro com níveis de risco (`Low`, `Medium`, `High`, `Critical`).
- 🛡️ **Ponto de Aprovação Human-in-the-Loop**: pausa a execução através do `interrupt()` do LangGraph, para que os engenheiros possam inspecionar, rever e modificar os níveis de risco ou o âmbito dos ficheiros em linguagem natural, antes de qualquer alteração ao código.
- 🛠️ **Workers de Refatorização em Paralelo**: são lançados em simultâneo através da API `Send()` do LangGraph (um worker por ficheiro do plano), gerando diffs de código precisos, análise de breaking changes e casos de teste recomendados.
- 📊 **Agente Agregador**: sintetiza todos os diffs dos ficheiros num Guia e Relatório de Migração pronto a publicar, gerando automaticamente 1-2 gráficos matplotlib orientados por dados (incorporados como imagens base64).
- 🖥️ **Interface Streamlit**: configuração da API na barra lateral, badges de risco, controlos de revisão interativos, renderização do relatório em markdown com gráficos incorporados e descarregamento em `.md` com um clique.
- ✅ **Validação de Consultas**: valida as entradas do repositório e os objetivos de migração para bloquear prompts vazios, inseguros ou destrutivos antes de chegarem aos LLMs.

## Como Executar

1. **Clonar o repositório**

```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. **Instalar as dependências**

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

3. **Executar a aplicação**

```bash
   streamlit run app.py
   ```

> **Configuração do LLM:** Adicione a sua chave a um ficheiro `.env` (ver `.env.example`) ou introduza-a na barra lateral da aplicação:
>

```env
> OPENAI_API_KEY=sk-your-key-here
> ```

>
> Por predefinição, utiliza `gpt-5-mini` para o planeamento e para os workers por ficheiro, e `gpt-5.5` para a síntese final do relatório. Pode substituir com `MODEL_FAST` / `MODEL_PRO`, ou apontar para qualquer fornecedor compatível com OpenAI definindo também `LLM_BASE_URL`.

## Como Funciona

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

1. **Query Validator** verifica que são fornecidos tanto um caminho/URL de repositório válido como um objetivo de migração substancial.
2. **Planner Agent** (saída estruturada) formula uma estratégia de migração de alto nível e divide as alterações em 3 a 6 tarefas de migração de ficheiros com níveis de risco estimados.
3. **Plan Approval Gate** pausa o grafo usando a API `interrupt()` do LangGraph para permitir que os programadores revejam a matriz de risco, solicitem revisões em linguagem natural ou aprovem a execução.
4. **Parallel Refactor Workers** distribuem o trabalho através de chamadas à API `Send()` (um ramo por ficheiro) para produzir diffs unificados, snippets antes/depois e casos de teste.
5. **Aggregator Agent** sintetiza todos os diffs de refatorização num relatório abrangente, escolhe os dados dos gráficos (não código executável), renderiza gráficos de risco visuais usando templates Matplotlib fidedignos e descreve os passos de validação pós-migração.

O estado da sessão é persistido usando o `MemorySaver` em memória do LangGraph, permitindo que as interrupções de execução persistam de forma transparente entre reexecuções do Streamlit.

## Exemplos de Casos de Utilização

- **Atualizações de Frameworks e Bibliotecas**: por exemplo, Pydantic v1 → v2 (`BaseModel`, `@validator` para `Field`, `@field_validator`), Flask 2 → 3, SQLAlchemy 1.4 → 2.0.
- **Conversões de Linguagem / Sintaxe**: por exemplo, converter ficheiros JavaScript (`.js`) para TypeScript (`.ts`) com interfaces estritas.
- **Refatorização Assíncrona e de Desempenho**: por exemplo, converter handlers síncronos de I/O e de base de dados para `async`/`await`.
- **Limpeza de Depreciações**: substituir padrões de API descontinuados em vários serviços de forma segura.

## Detalhes Técnicos

| Camada | Tecnologia |
|---|---|
| Grafo de Agentes | LangGraph (`Send()` fan-out, `interrupt()` HITL, `MemorySaver` checkpointer) |
| LLMs | Configurável (predefinições: `gpt-5-mini` para passos rápidos, `gpt-5.5` para a síntese) |
| Gráficos | Dados validados renderizados por templates Matplotlib fidedignos (data URIs PNG base64 incorporados) |
| UI | Streamlit |

## Dependências

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

## Licença

Este projeto faz parte da coleção awesome-llm-apps e está disponível ao abrigo da Licença Apache-2.0.

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/ai-codebase-migration-agent