jhonny-editor/rag

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