Detecção de Code Smells com LLMs: Estudo Experimental

Este repositório contém o código-fonte e os dados utilizados na pesquisa sobre a eficácia de Grandes Modelos de Linguagem (LLMs) na detecção de Code Smells em projetos Java.

📋 Resumo do Projeto

Pergunta Científica: Modelos de linguagem (especificamente GPT-4o) são capazes de identificar code smells complexos quando submetidos a diferentes estratégias de engenharia de prompt?

Abordagem: A pesquisa avalia a detecção de três smells principais: Long Method, Multifaceted Abstraction e Long Parameter List. O estudo é conduzido através de quatro experimentos progressivos:

1. EXP1 (Baseline): Detecção baseada apenas na menção do nome do smell.
2. EXP2 (Definições): Inclusão de definições teóricas detalhadas nos prompts.
3. EXP3 (Métricas): Enriquecimento do contexto com métricas estáticas de software (ex: LOC, CC, LCOM).
4. EXP4 (Tunning): Ajuste de hiperparâmetros (temperatura, top-p) para refinar a precisão.

Arquivos Principais:

• main.py: Orquestrador que executa o pipeline completo (download de dados -> experimentos -> relatórios).
• Experiments.py: Lógica de execução dos 4 experimentos.
• DataPreparation.py: Tratamento e normalização do dataset (Ground Truth).
• ExperimentsUtil.py: Definições de prompts, métricas e avaliação.

🚀 Passo a Passo (Quick Start)

Siga os comandos abaixo para configurar o ambiente e reproduzir os experimentos.

1. Pré-requisitos

• Python 3.8 ou superior.
• Uma chave de API válida (OpenAI ou compatível).

2. Configuração do Ambiente

Clone o repositório e crie um ambiente virtual para isolar as dependências:

Clone o repositório (exemplo)

git clone [https://github.com/seu-usuario/seu-repo.git](https://github.com/seu-usuario/seu-repo.git)
cd seu-repo

Crie o ambiente virtual (.venv)

python -m venv .venv

Ative o ambiente virtual

No Linux/Mac:

source .venv/bin/activate

No Windows:

.venv\Scripts\activate

3. Instalação de Dependências

Instale as bibliotecas necessárias listadas no requirements.txt:

pip install -r requirements.txt

O projeto requer uma variável de ambiente chamada AS_OPENAI_API_TOKEN. Faça:

Linux/Mac:

export AS_OPENAI_API_TOKEN="sua-chave-api-aqui"

Windows (PowerShell):

$env:AS_OPENAI_API_TOKEN="sua-chave-api-aqui"

4. Execução dos Experimentos

Para rodar todo o fluxo (download dos dados, execução dos EXP1-EXP4 e geração dos gráficos):

python main.py
Os resultados (tabelas CSV e gráficos) serão salvos na pasta raiz ou em subdiretórios gerados automaticamente.

🔬 Reprodutibilidade

Para garantir a transparência e reprodutibilidade deste estudo, detalhamos abaixo as configurações utilizadas:

Dataset:

O download é feito automaticamente pelo script (main.py) a partir de um repositório público no Google Drive.

Seeds:

O código utiliza sementes aleatórias padrão do Python. Recomenda-se configurar random.seed(42) e numpy.random.seed(42) caso deseje determinismo estrito (veja Issues do projeto).

Ambiente de Execução:

Python: 3.10+

Dependências principais:

pandas, scikit-learn, matplotlib, requests.

Hardware:

Como o processamento pesado ocorre via API externa, não é necessário GPU local. Uma CPU padrão é suficiente para o cálculo das métricas de avaliação.

🛠 Solução de Problemas (Troubleshooting)

Erro: ValueError: API key not found

• Causa: A variável de ambiente AS_OPENAI_API_TOKEN não foi definida.

• Solução: Volte ao passo 4 e certifique-se de exportar a variável no mesmo terminal onde executará o script.

Erro: Falha no download dos dados (FileNotFoundError ou CSV vazio)

• Causa: Link do Google Drive expirado ou bloqueio de rede.

• Solução: Verifique se o link em main.py ("download_url") está acessível via navegador. Se necessário, baixe o CSV manualmente e coloque na raiz do projeto.

Erro: ModuleNotFoundError

• Causa: Dependências não instaladas.

• Solução: Certifique-se de que o ambiente virtual (.venv) está ativo e rode:

pip install-r requirements.txt novamente.

---

Arquivo Adicional Necessário: requirements.txt

Como o passo a passo menciona o requirements.txt (e o seu código usa bibliotecas externas), você deve criar este arquivo na mesma pasta com o seguinte conteúdo, baseado nas importações que identifiquei em UtilitaryFunctions.py e ExperimentsUtil.py:

pandas
matplotlib
scikit-learn
requests