# Guia de RAG Lexical

## Quando usar

Use este recurso quando um tenant precisa que o ChatAgent consulte documentos proprios
durante conversas sem depender de embeddings ou de um vector database externo.

O RAG atual e **lexical**: usa SQLite FTS5 + BM25. Ele funciona bem quando a pergunta
compartilha termos/prefixos com o conteudo cadastrado. Nao e busca semantica por embeddings.

## Autenticacao

Use a API key geral do tenant:

```http
Authorization: Bearer chatag_...
```

As rotas nao usam a chave interna de imagem nem a API key de numero conectado.

## Como funciona

1. Seu sistema extrai o texto do documento.
2. Envia `title` + `content` para `/api/rag/documents`.
3. O ChatAgent quebra o texto em chunks de aproximadamente 1200 caracteres, preferindo
   limites de paragrafo quando possivel.
4. Os chunks entram numa tabela FTS5 isolada por tenant.
5. Em cada mensagem de chat, o ChatAgent busca ate quatro chunks relevantes usando BM25
   e injeta esse contexto no prompt antes de chamar o provider.

Nao existe parser de PDF dentro desta rota. Se a fonte for PDF, DOCX, pagina web etc.,
extraia o texto no seu sistema e envie o texto resultante em `content`.

## Criar documento

```http
POST /api/rag/documents
Authorization: Bearer chatag_...
Content-Type: application/json
```

```json
{
  "title": "Politica de reembolso 2026",
  "content": "Reembolsos podem ser solicitados em ate 7 dias..."
}
```

O body desta rota aceita ate aproximadamente 2 MB.

Resposta `201`:

```json
{
  "document": {
    "id": 12,
    "tenant_id": 4,
    "title": "Politica de reembolso 2026",
    "chunk_count": 3,
    "created_at": "2026-09-17 20:00:00"
  }
}
```

## Listar documentos

```http
GET /api/rag/documents
Authorization: Bearer chatag_...
```

Resposta:

```json
{
  "documents": [
    {
      "id": 12,
      "title": "Politica de reembolso 2026",
      "chunk_count": 3,
      "created_at": "2026-09-17 20:00:00"
    }
  ]
}
```

## Remover documento

```http
DELETE /api/rag/documents/12
Authorization: Bearer chatag_...
```

Resposta:

```json
{ "success": true }
```

Um ID inexistente ou pertencente a outro tenant retorna `404`.

## Uso no chat

Nao e necessario passar um ID de documento na conversa. Se o tenant possui documentos,
o mecanismo RAG roda automaticamente em `executeChat()` para cada mensagem e injeta os
chunks encontrados no contexto.

Exemplo:

```http
POST /api/chat
Authorization: Bearer chatag_...
Content-Type: application/json
```

```json
{
  "thread_id": "cliente-42",
  "message": "Qual e o prazo para pedir reembolso?"
}
```

O mesmo contexto RAG tambem beneficia caminhos de conversa que passam pelo motor comum
de chat do tenant.

## Caracteristicas e limites

- isolamento por `tenant_id`;
- FTS5/BM25 local, sem chamada adicional ao provider para buscar contexto;
- busca por tokens com pelo menos 3 caracteres e prefix matching (`token*`);
- ate 4 chunks por mensagem no comportamento atual;
- chunks de ate aproximadamente 1200 caracteres, sem overlap;
- nenhum endpoint de embeddings e necessario;
- nao ha busca vetorial/semantica hoje.

Como e lexical, sinonimos distantes podem nao encontrar o trecho esperado. Se o recall
for insuficiente, prefira textos com terminologia consistente e titulos claros; evolucao
para embeddings/vector search e uma capacidade diferente, nao implicita neste contrato.

## Erros comuns

- `401` — API key de tenant ausente/invalida.
- `400` — `title` ou `content` ausente/vazio, ou ID invalido no delete.
- `404` — documento nao encontrado no tenant autenticado.

## Checklist

- [ ] extrai o texto antes de cadastrar arquivos binarios
- [ ] usa API key do tenant
- [ ] cadastra documentos no tenant correto
- [ ] mantem terminologia proxima da que os usuarios usam nas perguntas
- [ ] remove/recadastra documento quando o conteudo de negocio mudar