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