wpp-rag-index

name	wpp-rag-index
description	Gerar ou atualizar a base RAG local (SQLite + sqlite-vec) do WPP4Delphi, que indexa a documentação (README/SPEC/CLAUDE.md/skills) e o código-fonte Pascal (Source/**/*.pas) para busca semântica, e consultá-la. Use quando o usuário pedir para "reindexar", "atualizar a base RAG", "gerar embeddings do projeto", ou "buscar/perguntar sobre o projeto via RAG/busca vetorial".

Base RAG do WPP4Delphi (SQLite + sqlite-vec)

Ferramenta local em Scripts/rag/ que gera uma base de busca semântica sobre este repositório: documentação (README.md, SPEC.md, CLAUDE.md, .claude/skills/*/SKILL.md) e todo o código Pascal em Source/**/*.pas. Os embeddings rodam 100% localmente (sentence-transformers, sem enviar código para nenhuma API externa) e ficam num único arquivo SQLite com a extensão sqlite-vec.

Arquivos

• Scripts/rag/common.py — config compartilhada (nome do modelo, caminho do DB, pastas excluídas).
• Scripts/rag/build_index.py — gera a base (sempre do zero — dropa e recria as tabelas; o projeto é pequeno o suficiente para isso ser mais simples e confiável que update incremental).
• Scripts/rag/query.py — CLI de consulta (busca por similaridade de embedding).
• Scripts/rag/requirements.txt — sqlite-vec, sentence-transformers.
• Scripts/rag/wpp4delphi.rag.sqlite — o banco gerado (não versionado — está no .gitignore; regenerar localmente quando precisar).

Como funciona

• Modelo de embeddings: paraphrase-multilingual-MiniLM-L12-v2 (384 dimensões) — multilíngue porque os comentários/identificadores do projeto misturam português e inglês. Baixado uma vez do Hugging Face e cacheado em ~/.cache/huggingface.
• Chunking de docs (.md): por seção de título (#/##/###), cada chunk carrega o título junto para continuar fazendo sentido isolado; seções muito grandes (>4000 caracteres) são sub-divididas.
• Chunking de Pascal (.pas): janela deslizante de 100 linhas com 20 de sobreposição, por arquivo — deliberadamente simples (sem parser de Object Pascal) para não repetir bugs de aninhamento de comentários ({ }, {$IFDEF}) já vistos neste projeto ao tentar quebrar por procedure/function.
• Schema SQLite: tabela chunks (texto + metadados: file_path, start_line/end_line ou heading) + tabela virtual vec_chunks (vec0) com o embedding, ligadas por rowid.

Gerar/atualizar a base (reindexar)

Rodar sempre que o código ou a documentação mudar de forma relevante — não há watch automático.

cd Scripts/rag
pip install -r requirements.txt   # só na primeira vez, ou se o venv for outro
python build_index.py

Leva ~1 min neste projeto (~700 chunks). Primeira execução é mais lenta por baixar o modelo (~470MB).

Consultar

cd Scripts/rag
python query.py "como funciona o envio de mensagem de texto"
python query.py "TWPPConnect.SendTextMessage" --top-k 8

Cada resultado mostra o arquivo (+ linhas, se for chunk de código, ou o título da seção, se for doc), a distância (menor = mais similar) e um trecho do conteúdo.

Notas de ambiente

• Requer Python 3.10+ (testado com 3.14) e pip install -r requirements.txt (inclui torch/transformers — download pesado na primeira instalação).
• Em Windows, sem symlinks habilitados (modo Developer OFF), o huggingface_hub emite um aviso sobre cache degradado — inofensivo, pode ignorar.
• query.py força stdout para UTF-8 no início — sem isso, o console do Windows corrompe os acentos do conteúdo em português retornado pela busca.
• Este script/skill é uma ferramenta de apoio para consulta humana ou de outro agente sobre o projeto — não é usado pelo componente TWPPConnect em si nem faz parte do pacote Delphi/Lazarus.