Introdução

Procurar informações em um repositório de código gigante pode ser frustrante. A resposta muitas vezes está ali, mas perdida em meio a centenas de arquivos. Ferramentas como grep resolvem buscas exatas, mas e se precisássemos de uma interpretação, uma "conversa" com o código?

Para explorar essa questão, desenvolvi este projeto. O objetivo não é criar uma ferramenta de produção, mas sim servir como um laboratório prático para apoiar os estudos sobre LLMs e a arquitetura RAG. É uma oportunidade de observar, com um exemplo concreto, como esses componentes funcionam juntos.

O foco do projeto foi criar um sistema capaz de responder a perguntas como:

• "Quem é o responsável pela DAG X?"
• "Qual a finalidade da função Y?"
• "Mostre-me as queries que utilizam a tabela XYZ."

O resultado foi uma ferramenta de linha de comando funcional e, mais importante, um grande aprendizado que compartilho a seguir.

Parte 1: A Ideia - RAG e o Papel Qualitativo do LLM

A base do projeto é a arquitetura RAG (Retrieval-Augmented Generation), que une uma busca eficiente com a capacidade de interpretação de um Modelo de Linguagem Grande (LLM).

O processo funciona em três etapas:

1. A Base de Conhecimento (Vector Store): Primeiro, o conteúdo do repositório é indexado. Um script lê, divide os arquivos em trechos (chunks) e usa um modelo de embedding para converter cada trecho em vetores numéricos, que são armazenados localmente.

2. O Detetive (Retriever): Quando uma pergunta é feita, o sistema busca na base de vetores os trechos de código mais relevantes. Esta é a etapa de recuperação de dados, puramente quantitativa: encontrar a informação exata.

3. O Intérprete (LLM): Aqui está o ponto crucial e o grande diferencial deste projeto. Os trechos de código encontrados são entregues ao LLM junto com a pergunta original. É neste momento que a mágica acontece.

LLMs para Respostas Qualitativas

Enquanto a busca (retriever) encontra o "o quê" (o trecho de código, a linha exata), o LLM é excepcional em fornecer o "porquê" e o "como". Sua força não está em encontrar dados, mas em sintetizar, resumir, explicar e inferir informações a partir do contexto fornecido. Ele transforma dados brutos em respostas qualitativas, que se assemelham à interpretação que um ser humano faria.

O melhor de tudo? Todo o processo acontece localmente na sua máquina, tornando-o um ambiente perfeito e sem custos para estudos e experimentos.

Parte 2: Mãos à Obra - Preparando o Ambiente

Vamos reunir as ferramentas necessárias para o nosso projeto.

Ambiente Python

Primeiro, certifique-se de ter o Python 3.8 (ou superior) instalado. Em seguida, crie uma pasta para o projeto e um ambiente virtual para manter as dependências organizadas.

mkdir code-qa-bot # Ou o nome que preferir
cd code-qa-bot
python3 -m venv .venv
source .venv/bin/activate

Ollama: IA na sua Máquina

O Ollama é a forma mais simples de rodar modelos de linguagem localmente. Baixe e instale a versão para o seu sistema operacional. Depois, via terminal, baixe o modelo que usaremos para gerar as respostas. Usaremos o gemma:2b, um modelo do Google leve e competente.

ollama pull gemma:2b

Abaixo, uma tabela comparativa para ajudar na escolha de outros modelos, caso queira experimentar:

Bibliotecas Python

Crie um arquivo requirements.txt com as seguintes dependências. Você pode ver o arquivo original aqui.

# Orquestração principal da pipeline RAG
langchain
langchain_community

# Ferramenta para rodar LLMs locais
ollama

# Integrações para componentes específicos
langchain-huggingface  # Para o modelo de embedding
langchain-chroma       # Para o vector store ChromaDB
langchain-ollama       # Para conectar ao LLM local via Ollama

# Provedor do modelo de embedding
sentence-transformers

# Banco de dados vetorial local
chromadb

# Utilitários para processamento de arquivos
PyYAML              # Para arquivos .yaml
sql-metadata        # Para arquivos .sql
lark

pytest

Agora, instale todas as bibliotecas de uma vez:

pip install -r requirements.txt

Parte 3: O Código - Construindo o Motor de Busca

Nossa ferramenta será modular, dividida em vários arquivos Python para maior clareza.

• config.py
  Este arquivo centraliza as configurações. A principal alteração que você deve fazer aqui é apontar a variável REPO_PATH para o caminho do seu repositório local.

• data_loader.py
  Aqui está o coração do pré-processamento. Em vez de tratar todos os arquivos como texto genérico, este módulo os analisa para extrair informações estruturadas e valiosas. É aqui que definimos o page_content e os metadata de cada "documento".

  ⚠️ Atenção: Ponto Crucial de Customização!
  As classes de processamento (YamlProcessor, SqlProcessor, etc.) foram desenhadas para uma estrutura de projeto específica. O seu repositório provavelmente terá uma organização diferente.

  Pense neste código como um template. A estratégia fundamental é criar "chunks" de informação inteligentes. Você precisará adaptar a lógica dentro de cada classe process para que ela entenda e extraia as informações mais relevantes do seu contexto.

  A importância de page_content e metadata

  Definir bem esses dois parâmetros é o segredo para uma busca precisa. Pense neles como uma ficha de catalogação de uma biblioteca:

  • page_content (O Conteúdo do Livro): É o texto que será efetivamente "lido" e vetorizado. Um page_content claro e rico em contexto gera uma representação vetorial muito mais fiel. Por exemplo, a frase "Este documento descreve a DAG com ID 'dag_exemplo'. O proprietário é 'ana.silva'." tem um significado semântico muito mais forte do que um bloco YAML bruto. É também esse conteúdo que o LLM usará para formular a resposta final.
  • metadata (A Etiqueta na Lombada): São os dados que descrevem o conteúdo, como dag_id, table_name, author, etc. A função mais poderosa do metadata é permitir a filtragem inteligente. Quando usamos um SelfQueryRetriever, ele primeiro usa os metadados para filtrar os documentos relevantes e só então faz a busca por similaridade semântica. Isso torna a busca dramaticamente mais rápida e precisa, evitando que o sistema se confunda com informações de arquivos não relacionados.

• vector_store.py
  
  Este arquivo gerencia a criação e o carregamento do nosso banco de dados vetorial persistente (ChromaDB).

• indexer.py
  
  Um script independente que você executa uma única vez (ou sempre que houver mudanças significativas no código) para popular o banco de dados vetorial.

• ask.py
  
  Este é o script interativo para fazer perguntas ao seu código. Ele configura o Self-Querying Retriever, o cérebro da nossa operação. Graças aos metadados ricos que definimos, o retriever usa o LLM para analisar sua pergunta e criar um filtro preciso antes mesmo de realizar a busca vetorial.

Parte 4: O Fluxo de Trabalho na Prática

Com todos os arquivos no lugar, usar a ferramenta se resume a duas etapas.

1. Indexe seu Repositório

Este passo único lê todos os arquivos do seu projeto, os processa e constrói o banco de dados vetorial.

❯ python indexer.py
Starting the indexing process...
Found and processed 19052 document chunks.
Creating new vector store...
Vector store created and saved.
✅ Indexing complete.

2. Faça suas Perguntas

Agora, inicie a ferramenta de Q&A e comece a conversar com seu código.

Exemplo 1: Pergunta sobre responsabilidade

❯ python ask.py
✅ Q&A Tool is ready. Ask questions about your codebase.
Ask a question (or type 'exit'): Who is the owner of the dag "process_seller_data_dag"?

--- Answer ---
ana.silva@suaempresa.com

--- Sources ---
- ./data/dags/process_seller_data_dag/dag.yaml

Ask a question (or type 'exit'): 

Exemplo 2: Pergunta sobre uso de tabelas

❯ python ask.py
✅ Q&A Tool is ready. Ask questions about your codebase.

Ask a question (or type 'exit'): Quais consultas utilizam a tabela 'analytics_prod.seller_reputation'?

--- Answer ---
Com base nos documentos fornecidos, a tabela `analytics_prod.seller_reputation` é utilizada principalmente na seguinte consulta SQL, encontrada no arquivo `classificacao_seller.sql`:

`SELECT ... FROM analytics_prod.seller_reputation WHERE ...`

Esta query parece ser central para calcular a classificação e o score dos vendedores.

Além disso, podemos inferir outros usos potenciais baseados na estrutura do projeto:

1.  **Relatórios de Performance:** A tabela é provavelmente uma fonte de dados para dashboards e relatórios que monitoram a performance dos vendedores.
2.  **Análises de Dados:** Consultas de agregação (`GROUP BY`) podem ser usadas para analisar tendências e padrões no comportamento dos vendedores.
3.  **Lógica de Negócio:** Os dados podem disparar processos automáticos, como o envio de notificações para vendedores com base em sua performance.

Para uma lista exaustiva, seria necessário analisar todas as dependências que consomem os outputs desta DAG.

--- Sources ---
- ./data/dags/process_seller_data_dag/assets/json/classificacao_seller.json
- ./data/dags/process_seller_data_dag/readme.md
- ./data/dags/process_seller_data_dag/sql/taxa_score/classificacao_seller.sql
- ./data/dags/process_seller_data_dag/sql/taxa_score/sellers.sql

Ask a question (or type 'exit'):

+---------------------------+
|   Pergunta do Usuário     |
| (Ex: "Descreva a DAG...") |
+---------------------------+
             |
             v
+--------------------------------------+
| 1. O Retriever busca os documentos   |
|    mais relevantes no Vector Store.  |
+--------------------------------------+
             |
             v
+--------------------------------------+
| 2. O conteúdo dos documentos         |
|    (page_content) é enviado para o   |
|    LLM como contexto.                |
+--------------------------------------+
             |
             v
+--------------------------------------+
| 3. O LLM lê o contexto e gera uma    |
|    resposta em texto (resumo).       |
+--------------------------------------+
             |
             v
+---------------------------+
|   Resposta para o Usuário |
+---------------------------+

Repositório no github