rag-service/docs/API_RAG.md

# API del RAG

**Proyecto:** Workspace de tools IA para empresas  
**Modulo:** RAG  
**Ultima actualizacion:** 2026-09-08
**Ultima modificacion por:** Agente RAG 2
**Estado:** Operativa y validada en produccion

Esta guia explica como descubrir y consumir la API. El contrato tecnico completo y canonico se publica en OpenAPI 3.1.1; este documento prioriza el camino rapido, las decisiones de uso y los ejemplos habituales.

## Acceso rapido

Base URL de produccion:

```text
https://rag.por-correo.com
```

| Recurso | URL | Uso |
|---|---|---|
| Ayuda resumida | `GET /help` | Descubrimiento rapido para personas y agentes |
| Contrato OpenAPI | `GET /openapi.json` | Esquemas, parametros, respuestas y errores |
| Playground | `GET /playground` | Pruebas manuales desde navegador |

La API no requiere autenticacion actualmente. No debe asumirse que esta situacion es definitiva: la autenticacion y la proteccion de operaciones sensibles forman parte del pendiente 5.

## Elegir la operacion correcta

| Necesidad | Endpoint recomendado |
|---|---|
| Comprobar servicio y capacidades | `GET /health` |
| Ver scopes ingeridos | `GET /sources` |
| Recuperar contexto para otro agente | `POST /retrieve` |
| Obtener una respuesta final con citas | `POST /answer` |
| Comparar una respuesta sin RAG | `POST /answer/direct` |
| Conversar con bootstrap e historial | `POST /chat` |
| Ingerir una ruta accesible por el servidor | `POST /ingest` |
| Subir un archivo o carpeta ZIP | `POST /ingest/upload` |
| Eliminar una fuente antes de reingestar | `POST /cleanup` |
| Consultar o actualizar evaluaciones | `/logs/*` |

## Catalogo completo

La API queda formada por 16 operaciones tras incorporar el descubrimiento:

| Metodo | Ruta | Descripcion |
|---|---|---|
| `GET` | `/help` | Catalogo resumido derivado de OpenAPI |
| `GET` | `/openapi.json` | Contrato OpenAPI 3.1.1 |
| `GET` | `/playground` | Interfaz web de prueba |
| `GET` | `/health` | Estado, proveedores, parsers y chunking |
| `GET` | `/sources` | Scopes disponibles en Qdrant |
| `GET` | `/models/answer` | Modelo por defecto y modelos seleccionables |
| `POST` | `/ingest` | Ingesta desde una ruta del servidor |
| `POST` | `/ingest/upload` | Upload `multipart/form-data` |
| `POST` | `/cleanup` | Borrado controlado por scope |
| `POST` | `/retrieve` | Recuperacion de contexto |
| `POST` | `/answer` | Respuesta apoyada en retrieval |
| `POST` | `/answer/direct` | Respuesta del modelo sin retrieval |
| `POST` | `/chat` | Conversacion con contexto opcional |
| `GET` | `/logs/recent` | Logs recientes de evaluacion |
| `POST` | `/logs/manual` | Registro manual de una evaluacion |
| `PATCH` | `/logs/{id}` | Seguimiento y resolucion de un log |

## Contratos comunes

### Scope

Permite limitar una consulta o una operacion a fuentes concretas:

```json
{
  "sourceId": "customer-a:manual:v1",
  "sourceRef": "customer-a-errors.md",
  "tags": ["customer-a", "support"]
}
```

Todos los campos son opcionales en consultas. Para `POST /cleanup` es obligatorio enviar al menos `sourceId` o `sourceRef`; las etiquetas solas no autorizan un borrado.

### Modos e intents

| Campo | Valores | Default |
|---|---|---|
| `mode` en retrieval y answer | `documental`, `codigo`, `auto` | `auto` |
| `mode` en chat | `documental`, `codigo`, `auto` | `documental` |
| `intent` | `specific`, `bootstrap` | `specific` |
| `mode` en ingesta | `mechanical`, `interactive` | `mechanical` |

### Errores

Los errores JSON siguen esta forma:

```json
{
  "ok": false,
  "error": "Description of the error"
}
```

Actualmente la mayoria de fallos de validacion o de proveedores se devuelven como `500`. `POST /cleanup` y `POST /ingest/upload` tambien pueden devolver `400`, y `PATCH /logs/{id}` devuelve `404` si no encuentra el log. Mejorar la validacion queda fuera de este bloque para no cambiar silenciosamente el comportamiento existente.

## Recuperar contexto

`POST /retrieve` es la operacion recomendada cuando otro agente o flujo generara la respuesta final.

```bash
curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "What does error FAT07 mean?",
    "scope": {
      "sourceId": "customer-a:manual:v1"
    },
    "useModelInRetrieve": false
  }'
```

Campos principales:

| Campo | Requerido | Funcion |
|---|---|---|
| `query` | Si | Consulta de recuperacion |
| `mode` | No | Tipo de conocimiento |
| `intent` | No | Consulta concreta o mapa bootstrap |
| `scope` | No | Limita las fuentes |
| `useModelInRetrieve` | No | Añade `modelSummary` generado por un modelo |
| `model` | No | Override usado solo para `modelSummary` |
| `bootstrapMeta` | No | Trazabilidad del bootstrap en logs |

Respuesta resumida:

```json
{
  "mode": "documental",
  "intent": "specific",
  "summary": "Retrieved 5 relevant chunks.",
  "topics": ["support-errors.md"],
  "criticalPoints": [],
  "items": [
    {
      "chunkId": "chk:example",
      "documentId": "doc:example",
      "sourceId": "customer-a:manual:v1",
      "title": "support-errors.md",
      "content": "...",
      "score": 0.87
    }
  ],
  "followUpRefs": ["doc:example"],
  "scope": {
    "sourceId": "customer-a:manual:v1"
  }
}
```

## Obtener una respuesta

`POST /answer` ejecuta retrieval y genera una respuesta final con citas.

```json
{
  "mode": "documental",
  "intent": "specific",
  "query": "Explain the documented resolution for FAT07",
  "scope": {
    "sourceId": "customer-a:manual:v1"
  },
  "model": "openai/gpt-4.1-mini"
}
```

Tambien acepta `preloadedContext` y `bootstrapMeta`. La respuesta incluye `model`, `answer`, resumen del retrieval, temas, puntos criticos, citas y scope.

`POST /answer/direct` no consulta el vector store:

```json
{
  "query": "Explain what a RAG service is",
  "model": "openai/gpt-4.1-mini",
  "preloadedContext": "Optional context supplied by the caller"
}
```

Su respuesta real solo contiene:

```json
{
  "model": "openai/gpt-4.1-mini",
  "answer": "..."
}
```

## Chat con bootstrap

`POST /chat` reutiliza contexto precargado, historial reciente y, opcionalmente, una nueva consulta al RAG:

```json
{
  "message": "What should I check next?",
  "history": [
    {
      "role": "user",
      "content": "Give me an initial map of this project"
    },
    {
      "role": "assistant",
      "content": "The project contains..."
    }
  ],
  "mode": "documental",
  "preloadedContext": "Previously loaded bootstrap",
  "allowAdditionalRetrieve": true,
  "scope": {
    "sourceId": "project-docs"
  }
}
```

Respuesta:

```json
{
  "model": "openai/gpt-4.1-mini",
  "answer": "...",
  "usedBootstrapContext": true,
  "usedAdditionalRetrieve": true,
  "retrieved": {
    "summary": "...",
    "items": []
  }
}
```

## Ingesta

### Ruta del servidor

`POST /ingest` requiere `sourceType` y `sourceRef`:

```json
{
  "sourceId": "project-docs",
  "sourceType": "folder",
  "sourceRef": "/data/project-docs",
  "mode": "mechanical",
  "tags": ["project", "documentation"]
}
```

`readPath` es un campo interno para separar la ruta fisica de lectura de la referencia logica. Los consumidores normales no deben enviarlo.

### Upload

`POST /ingest/upload` usa `multipart/form-data`:

| Campo | Requerido | Formato |
|---|---|---|
| `file` | Si | Archivo binario o ZIP |
| `sourceId` | No | Identificador logico |
| `mode` | No | `mechanical` o `interactive` |
| `tags` | No | Lista separada por comas |
| `isZipFolder` | No | Texto `true` o `false` |

```bash
curl -sS -X POST "https://rag.por-correo.com/ingest/upload" \
  -F "file=@./support-errors.md" \
  -F "sourceId=customer-a:manual:v1" \
  -F "mode=mechanical" \
  -F "tags=customer-a,support"
```

Ambas variantes responden `202` con el origen aceptado, archivos descubiertos, documentos procesados, chunks almacenados y coleccion. El upload añade `uploadedResource`.

## Limpieza controlada

`POST /cleanup` elimina los chunks que coinciden con un scope:

```json
{
  "scope": {
    "sourceId": "customer-a:manual:v1"
  }
}
```

Respuesta:

```json
{
  "ok": true,
  "deleted": 36
}
```

Esta operacion es destructiva. Verifica primero el scope con `GET /sources`.

## Evaluacion

`GET /logs/recent?limit=20` devuelve los logs recientes. Si no se indica `limit`, usa 20.

`POST /logs/manual` registra una observacion humana:

```json
{
  "operation": "retrieve",
  "reason": "manual_review_requested",
  "query": "What does error FAT07 mean?",
  "mode": "documental",
  "intent": "specific",
  "scope": {
    "sourceId": "customer-a:manual:v1"
  },
  "note": "The first result is too generic"
}
```

`PATCH /logs/{id}` actualiza su seguimiento:

```json
{
  "reviewStatus": "resolved",
  "severity": "high",
  "reviewedBy": "maintainer",
  "resolutionNote": "Retrieval ranking adjusted and validated.",
  "fixReference": "commit-or-ticket-reference"
}
```

Valores admitidos:

| Campo | Valores |
|---|---|
| `reviewStatus` | `pending`, `in_progress`, `resolved`, `ignored` |
| `severity` | `low`, `medium`, `high` |

## Integracion recomendada con n8n

Para una `HTTP Request Tool` conectada a un AI Agent:

1. Usa `POST /retrieve`.
2. Fija `mode`, `intent` y `scope` en el nodo.
3. Permite que el agente complete solo `query`.
4. Mantiene `useModelInRetrieve=false` para evitar procesar la consulta con dos modelos.
5. Entrega `items[].content` y sus metadatos al agente final.

Usa `POST /answer` solamente cuando el propio RAG deba generar la respuesta final.

## Fuente de verdad y mantenimiento

- `GET /openapi.json` es el contrato publico para integraciones y herramientas.
- `GET /help` es el indice rapido derivado del mismo contrato.
- Este documento explica flujos y decisiones de uso.
- `src/app.ts` contiene la implementacion efectiva.
- Cualquier cambio de endpoint debe actualizar OpenAPI y esta guia en el mismo bloque de trabajo.