João HenriqueandClaude Sonnet 5
e9a17c1b62
Cria rag/ (schema, busca híbrida densa+lexical com RRF em search.py/ search_gart.sh, SETUP.md) — o projeto já tinha admin/update_rag.py para indexar, mas nenhuma forma de consultar o índice. Corrige admin/update_rag.py: um chunk denso em tokens (code/fcpxml/font_metrics.py) estourava o contexto do modelo de embedding e derrubava a transação inteira; agora só aquele chunk é pulado. Banco rag_gart provisionado no rag-hub-db compartilhado e primeira indexação completa rodada (304 arquivos, 1702 chunks). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
# 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`](../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`](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`](search.py) e o wrapper
|
|
[`search_gart.sh`](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.
|