| 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
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.
