npm package: @stg_digital/n8n-nodes-rag-api
Description: Nodes n8n para API RAG Multi-Domínio - Busca semântica, ingestão de documentos e gerenciamento de banco de dados vetorial
Author: STG Digital
Latest version: 1.5.0

# n8n-nodes-rag-api

Custom n8n nodes para integração com RAG API - Busca semântica com dropdown de tabelas.

## Novidades v1.2.0

- **Dropdown de Tabelas** - Selecione a tabela diretamente no node (carrega automaticamente da API)
- **Autenticação simplificada** - Use apenas o API Token (não expira)
- **Sem limite de resultados** - Retorna todos os documentos por padrão
- **Nova rota GET** - Query via URL path para melhor integração

## Nodes Incluídos

| Node | Descrição |
|------|-----------|
| **RAG Consulta** | Busca semântica com dropdown de tabelas |
| **RAG Upload** | Upload de arquivos (PDF, DOCX, TXT, imagens) |
| **RAG Ingestão** | Ingerir documentos via JSON |
| **RAG Pastas** | Gerenciar tabelas (criar, listar, deletar) |
| **RAG Arquivos** | Gerenciar arquivos enviados |

## Instalação

### Opção 1: npm Link (Desenvolvimento)

```bash
cd n8n_nodes
npm install
npm run build
npm link

# Na pasta do n8n
npm link @stg_digital/n8n-nodes-rag-api
```

### Opção 2: Docker

```dockerfile
COPY n8n_nodes /home/node/.n8n/custom/n8n-nodes-rag-api
RUN cd /home/node/.n8n/custom/n8n-nodes-rag-api && npm install && npm run build
```

### Opção 3: Instalação Local

```bash
# Copie para a pasta custom do n8n
cp -r n8n_nodes ~/.n8n/custom/n8n-nodes-rag-api
cd ~/.n8n/custom/n8n-nodes-rag-api
npm install && npm run build
```

Reinicie o n8n após a instalação.

## Configuração

### 1. Criar Credencial

1. No n8n: **Credentials** → **New Credential** → **RAG API**
2. Configure:
   - **URL Base**: `http://seu-servidor:8000`
   - **API Token**: Seu token (encontre em API Docs no painel)

O API Token **não expira** e é usado automaticamente em todas as requisições.

### 2. Usar os Nodes

Os nodes carregam automaticamente as tabelas disponíveis quando você configura a credencial.

## Uso

### RAG Consulta (Busca)

O node principal para buscar documentos.

```
┌─────────────────────────────────┐
│ Tabela: [Carros (150 docs)]  ▼ │  ← Dropdown automático
│ Consulta: carros até 100 mil   │
│                                 │
│ Opções: (opcional)              │
│   Limite: 0 (sem limite)        │
│   Score Mínimo: 0               │
└─────────────────────────────────┘
```

**Saída:**
```json
{
  "folder": "Carros",
  "query": "carros até 100 mil",
  "total_results": 25,
  "query_time_ms": 234,
  "results": [
    {
      "content": "Honda Civic 2020 - R$ 95.000...",
      "score": 0.89,
      "metadata": {
        "source": "catalogo.pdf",
        "fileUrl": "/api/files/abc123",
        "isImage": false
      }
    }
  ]
}
```

### RAG Upload

Upload de arquivos com processamento automático.

```
┌─────────────────────────────────┐
│ Tabela: [Carros (150 docs)]  ▼ │
│ Tipo: Dados Binários            │
│ Propriedade: data               │
└─────────────────────────────────┘
```

Tipos suportados: PDF, DOCX, TXT, JSON, imagens.

### RAG Ingestão

Ingerir documentos via JSON (ideal para dados estruturados).

```
┌─────────────────────────────────┐
│ Tabela: [Produtos (50 docs)] ▼ │
│ Tipo: Documento Único           │
│ Conteúdo: {{$json.descricao}}   │
│ Metadados: {"preco": 100}       │
└─────────────────────────────────┘
```

### RAG Pastas

Gerenciar tabelas/coleções.

- **Listar Todos** - Lista todas as tabelas com contagem de docs
- **Criar** - Cria nova tabela
- **Deletar** - Remove tabela e todos os documentos
- **Obter Info** - Informações de uma tabela

### RAG Arquivos

Gerenciar arquivos enviados.

- **Listar** - Todos os arquivos
- **Listar por Tabela** - Arquivos de uma tabela específica (dropdown)
- **Obter** - Baixar arquivo por ID
- **Deletar** - Remover arquivo

## Exemplo de Fluxo

```
[Trigger] → [RAG Consulta] → [AI Agent] → [Responder]
                 ↓
         "carros até 100k"
                 ↓
         [25 resultados com
          imagens + descrições]
                 ↓
         [Agent monta resposta
          para o cliente]
```

## API Reference

| Endpoint | Método | Node |
|----------|--------|------|
| `/api/query/:folderId` | GET | RAG Consulta |
| `/api/query` | POST | RAG Consulta |
| `/api/upload` | POST | RAG Upload |
| `/api/admin/ingest` | POST | RAG Ingestão |
| `/api/admin/folders` | GET, POST | RAG Pastas |
| `/api/admin/folders/:name` | GET, DELETE | RAG Pastas |
| `/api/files` | GET | RAG Arquivos |
| `/api/files/folder/:id` | GET | RAG Arquivos |
| `/api/files/:id` | GET, DELETE | RAG Arquivos |

## Autenticação

Todas as requisições usam o header `X-API-Key` automaticamente:

```
X-API-Key: seu-api-token
```

O token é obtido no painel da aplicação (API Docs) e não expira.

## Changelog

### v1.2.0
- Dropdown de tabelas carregado automaticamente da API
- Autenticação via X-API-Key (token não expira)
- Query sem limite por padrão (retorna todos os resultados)
- Nova rota GET /api/query/:folderId
- Removido campo JWT das credenciais

### v1.1.0
- Suporte a upload de arquivos
- Gerenciamento de arquivos
- Múltiplos tipos de entrada na ingestão

### v1.0.0
- Release inicial
- Nodes básicos: Query, Ingest, Folders

## License

MIT