gart/rag/README.md

RAG deste projeto (G-ART)

Banco de RAG próprio do G-ART — usado só para a IA indexar código/documentação e responder consultas gastando menos tokens, sem precisar reler o repositório inteiro a cada tarefa. Não é o banco de dados do sistema: é infraestrutura de apoio ao desenvolvimento, mantida à parte da aplicação.

Segue o mesmo padrão dos projetos irmãos (Doza, Tigre, Jhonny): um único container Postgres + pgvector compartilhado (rag-hub-db) na VPS da equipe, e um banco por sistema dentro dele.

rag-hub-db (container único na VPS)
├── rag_doza    ← banco do Doza
├── rag_tigre   ← banco do Tigre
├── jhonny-rag  ← banco do Jhonny
└── rag_gart    ← banco deste projeto

Divisão de responsabilidades neste projeto

Diferente dos projetos irmãos, aqui a indexação já existia antes desta pasta e mora em admin/, não em rag/:

• Indexação — admin/update_rag.py, chamado por admin/update_rag.command (túnel SSH + execução) e por admin/run.command (roda junto com o app). Varre INCLUDE_EXTENSIONS (.command .md .py .sh .sql .swift .txt .yml .yaml) a partir da raiz do projeto, corta por janela de linhas (CHUNK_LINES), grava embeddings via Ollama e é incremental (hash por arquivo em gart.indexed_files).
• Schema — schema.sql nesta pasta: é o que admin/update_rag.py espera encontrar (gart.code_chunks, gart.file_index, gart.indexed_files). Rodar uma vez para provisionar um banco novo.
• Busca — search.py e o wrapper search_gart.sh nesta pasta: é o que os projetos irmãos chamam de search_<projeto>.sh. Não existia ainda para o G-ART.
• Credenciais — reaproveitadas de admin/gart-rag.env (mesmo arquivo que admin/update_rag.command já usa), para não duplicar a senha em dois lugares. Ver admin/gart-rag.env.example para o formato.

Como a busca funciona

Duas listas em paralelo, fundidas com RRF ponderado (parâmetros herdados dos projetos irmãos, calibrados lá via rag/bench.py sobre consultas douradas):

1. densa — embedding do trecho de código/texto;
2. lexical — pg_trgm sobre os símbolos declarados (nomes de classe/função extraídos por regex em admin/update_rag.py), para consultas que citam o nome exato de algo;
3. resumo (file_index.summary_embedding) — hoje não é preenchido por admin/update_rag.py (só grava summary em texto, sem embedding), então essa lista fica vazia até alguém adicionar isso ao indexador. A busca funciona normalmente sem ela.

Cada trecho guarda start_line/end_line, então o resultado aponta a janela exata (code/fcpxml/writer/modifier.py:120-180) em vez de mandar ler o arquivo inteiro.

Modos de saída

Comando	O que traz
rag/search_gart.sh "consulta"	caminho, faixa de linhas e uma linha de descrição (padrão)
… --snippet	+ 300 chars do trecho
… --full	+ o trecho inteiro
… --json	saída estruturada
… --module X / --path Y / --ext .py	restringe o escopo
… --map [termo]	inventário de arquivos, sem nenhum código

Arquivos desta pasta

• README.md — este arquivo.
• SETUP.md — passo a passo para provisionar o banco rag_gart na primeira vez.
• schema.sql — schema do G-ART (extensões, tabelas, índices). Estado FINAL desejado: num banco novo basta rodá-lo.
• embed.py — chamada ao Ollama compartilhada entre indexador e busca (só os prefixos search_document:/search_query: do nomic-embed-text).
• search.py / search_gart.sh — busca híbrida e seu wrapper.
• ensure_tunnel.sh — abre o túnel SSH até rag-hub-db se ainda não estiver aberto (idempotente).

Onde ficam as credenciais reais

Nunca nesta pasta. Credenciais de indexação (usuário/senha do Postgres) ficam em admin/gart-rag.env (fora do git). Acesso SSH à VPS e senha do usuário admin do rag-hub-db ficam documentados no VPS-ACCESS.md de outro projeto da equipe que já usa a mesma VPS — peça a quem provisionou o banco.