# RAG deste projeto

Esta pasta é o **padrão Genial Sistemas** para dar a qualquer sistema (CRM,
Doza, contabilidade, o que vier depois) um banco de RAG próprio — 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 em si.

## Como funciona a infra

Existe **um único container Postgres + pgvector** compartilhado, rodando na
VPS da equipe (`rag-hub-db`, em `/docker/rag-hub/`). Cada sistema recebe o
seu **próprio banco de dados** dentro desse container — não um container
Docker novo por projeto. Isso é intencional: mais barato de manter (1
backup, 1 upgrade, 1 lugar pra olhar) do que uma stack isolada por sistema.

```
rag-hub-db (container único na VPS)
├── rag_doza          ← banco deste projeto
├── rag_crm           ← banco do CRM (quando existir)
├── rag_contabilidade ← banco da contabilidade (quando existir)
└── ...               ← um banco por sistema novo
```

## Arquivos desta pasta

- `README.md` — este arquivo.
- `SETUP.md` — passo a passo para provisionar o banco deste projeto na
  primeira vez (ou reprovisionar do zero).
- `schema.sql` / `schema-tigre.sql` — schema de cada sistema (extensões,
  tabelas, índices). São o estado FINAL desejado: num banco novo basta
  rodá-los. Num banco que já existe, use as migrations.
- `migrations/` — mudanças de schema numeradas e idempotentes, aplicadas com
  `migrate_tigre.sh` (precisa de `rag_admin`; o usuário de indexação não tem
  DDL). Cada arquivo abre com o motivo da mudança e o que fazer depois.
- `index_code.py` — indexador. `swift_chunker.py` faz o corte de arquivos
  Swift por declaração.
- `search.py` — busca. `bench.py` mede recall e custo.
- `reindex_hook.sh` — hook de reindexação do arquivo recém-editado.
- `.env.example` — variáveis de ambiente que o código deste projeto precisa
  para se conectar ao banco (sem valores reais — apenas o formato).

## Como a busca funciona

Três listas em paralelo, fundidas com RRF ponderado:

1. **densa** — embedding do trecho de código;
2. **lexical** — `pg_trgm` sobre os símbolos declarados, para consultas que
   citam o nome exato de um tipo;
3. **resumo** — embedding só do doc-comment do arquivo, sem código para
   diluir, que resgata arquivos pequenos e precisos.

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

Os números que justificam esse desenho estão em `bench.py` (18 consultas
douradas) e nos cabeçalhos das migrations. Antes: recall@5 de 33%. Depois:
94%, com 67% menos bytes por consulta. **Ao mexer nos parâmetros de fusão ou
no cortador, rode `bench.sh` antes e depois.**

### Modos de saída

| Comando | O que traz |
|---|---|
| `search_tigre.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 .swift` | restringe o escopo |
| `… --map [termo]` | inventário de arquivos, sem nenhum código |

### Os dois bancos, lado a lado

O mesmo `search.py`/`index_code.py` atende `rag_tigre` (Swift) e `rag_doza`
(Python legado) — só muda o wrapper (`_tigre.sh` / `_doza.sh`) e o `.env`
carregado. `index_code.py` escolhe o cortador pela extensão:
`swift_chunker.py` para `.swift`, `python_chunker.py` para `.py`, janela de
linhas para o resto (`.md`, `.sql`, `.sh`).

O legado tem uma diferença estrutural real: não segue "uma classe por
arquivo" (`ai_analysis.py` e `app.py` passam de 5000 linhas, com dezenas de
funções soltas), então o `python_chunker` desce um nível dentro de blocos
grandes demais em vez de aceitar o arquivo inteiro como um só trecho.

Números do legado em `rag/bench_doza.sh`: recall@5 de 72% (18 consultas).
Mais baixo que os 94% do Tigre — a causa identificada não é bug do
pipeline, é o modelo de embedding (`nomic-embed-text`, majoritariamente
inglês) perdendo para conteúdo em português que soa tematicamente próximo:
"transcrever o áudio para texto" caiu atrás de markdown em português sobre
edição de voz, na frente do próprio `transcribe.py` (docstring em inglês).
Um modelo multilíngue deve fechar essa lacuna — ver README no que muda ao
trocar de modelo antes de decidir.

## Onde ficam as credenciais reais

Nunca neste diretório (ele é comitado no git). Credenciais reais —
host da VPS, senha do Postgres, chave SSH — ficam em `admin/VPS-ACCESS.md`
na raiz do projeto (nunca comitado, `chmod 600`).

## Convenção para um sistema novo

Ao começar um sistema novo (ou adicionar RAG a um já existente):

1. Copiar esta pasta `rag/` inteira para a raiz do novo projeto.
2. Trocar todas as referências de `doza`/`rag_doza` pelo nome do novo
   sistema (ex: `crm` → banco `rag_crm`).
3. Seguir `SETUP.md` para criar o banco na VPS (usa a mesma `rag-hub-db`,
   não sobe container novo).
4. Preencher `admin/VPS-ACCESS.md` do novo projeto com as credenciais reais
   (copiando o padrão de acesso SSH/túnel já documentado nos projetos
   existentes).