Planeador de Migração e Refatoração de Base 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

   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

   pip install -r requirements.txt

3. Executar a aplicação

   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:

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

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.