# API del RAG

**Proyecto:** Workspace de tools IA para empresas  
**Modulo:** RAG  
**Ultima actualizacion:** 2026-04-05  
**Ultima modificacion por:** Agente tools IA para potenciar servicios empresariales  
**Estado:** Operativa en VPS2

---

## Proposito

Dejar una referencia rapida y practica de la API del servicio `RAG` para poder conectarlo facilmente desde modelos, agentes, flujos de `n8n` y otras aplicaciones.

---

## Base URL actual

Produccion actual en `VPS2`:

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

---

## Endpoints disponibles

### 1. `GET /health`

Sirve para comprobar si el servicio esta levantado y si la conexion con `Qdrant` esta operativa.

Ejemplo:

```bash
curl -sS "https://rag.por-correo.com/health"
```

Respuesta esperada aproximada:

```json
{
  "ok": true,
  "service": "rag",
  "environment": "production",
  "embeddings": {
    "provider": "openrouter",
    "model": "qwen/qwen3-embedding-8b"
  },
  "answer": {
    "provider": "openrouter",
    "model": "openai/gpt-4.1-mini"
  },
  "vectorStore": {
    "ok": true,
    "kind": "qdrant"
  }
}
```

---

### 2. `POST /ingest`

Sirve para ingerir una fuente en el RAG.

Puede usarse sobre:
- un archivo
- una carpeta

Payload base:

```json
{
  "sourceType": "folder",
  "sourceRef": "/ruta/a/la/carpeta",
  "mode": "mechanical",
  "tags": ["workspace", "global-docs"]
}
```

Campos:

- `sourceId`: opcional, permite aislar la fuente en un scope propio
- `sourceType`: `file` o `folder`
- `sourceRef`: ruta de la fuente
- `readPath`: uso interno cuando se sube un archivo y el backend lo procesa desde una ruta temporal
- `mode`: `mechanical` o `interactive`
- `tags`: etiquetas opcionales para clasificar la fuente

Ejemplo documental:

```bash
curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "folder",
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs",
    "mode": "mechanical",
    "tags": ["workspace", "global-docs"]
  }'
```

Ejemplo codigo:

```bash
curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "folder",
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src",
    "mode": "mechanical",
    "tags": ["rag", "module-code"]
  }'
```

Respuesta esperada aproximada:

```json
{
  "accepted": true,
  "filesDiscovered": 10,
  "documentsProcessed": 10,
  "chunksStored": 45,
  "collectionName": "rag_chunks"
}
```

Ejemplo de aislamiento en un scope propio:

```bash
curl -sS -X POST "https://rag.por-correo.com/ingest" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "src:default:manual:pdf-tecnico-cliente-a",
    "sourceType": "file",
    "sourceRef": "/ruta/a/documento.pdf",
    "mode": "mechanical",
    "tags": ["cliente-a", "pdf-tecnico"]
  }'
```

---

### 3. `POST /retrieve`

Sirve para recuperar contexto del RAG sin pedir una respuesta final al modelo.

Es ideal para:
- agentes IA
- nodos tool de n8n
- flujos que quieran contexto rico y trazable

Payload base:

```json
{
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

Campos:

- `mode`:
  - `documental`
  - `codigo`
  - `auto`
- `intent`:
  - `specific`
  - `bootstrap`
- `query`: consulta del usuario o del flujo
- `scope` opcional:
  - `sourceId`
  - `sourceRef`
  - `tags`

Nota util:
- si una ingesta se hizo con `sourceId` propio, despues puedes consultar solo ese material usando `scope.sourceId`

#### Ejemplo `retrieve` documental

```bash
curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "que tenemos pendiente por hacer en este workspace",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'
```

#### Ejemplo `retrieve` bootstrap

```bash
curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "bootstrap",
    "query": "dame un mapa inicial del workspace y sus lineas de trabajo principales",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'
```

#### Ejemplo `retrieve` codigo

```bash
curl -sS -X POST "https://rag.por-correo.com/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "codigo",
    "intent": "specific",
    "query": "como se construye source_id en el rag",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
    }
  }'
```

Respuesta resumida esperada:

```json
{
  "mode": "documental",
  "intent": "specific",
  "summary": "...",
  "topics": ["PENDIENTES_GENERALES.md"],
  "criticalPoints": [],
  "items": [
    {
      "chunkId": "chk:...",
      "documentId": "doc:...",
      "sourceId": "src:...",
      "title": "PENDIENTES_GENERALES.md",
      "sectionTitle": "Resumen rapido",
      "content": "...",
      "score": 0.87
    }
  ],
  "followUpRefs": ["doc:..."],
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

---

### 4. `POST /answer`

Sirve para pedir al RAG una respuesta final apoyada en el contexto recuperado.

Es util para:
- agentes conversacionales
- respuestas listas para usuario
- pruebas rapidas desde n8n o aplicaciones

Tambien permite indicar el modelo de respuesta explicitamente mediante el campo opcional `model`.

Payload base:

```json
{
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

#### Ejemplo `answer` documental

```bash
curl -sS -X POST "https://rag.por-correo.com/answer" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "documental",
    "intent": "specific",
    "query": "que tenemos pendiente por hacer en este workspace",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
    }
  }'
```

#### Ejemplo `answer` codigo

```bash
curl -sS -X POST "https://rag.por-correo.com/answer" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "codigo",
    "intent": "specific",
    "query": "como se construye source_id en el rag",
    "scope": {
      "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
    }
  }'
```

Respuesta resumida esperada:

```json
{
  "mode": "codigo",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "answer": "...",
  "summary": "...",
  "topics": ["ids.ts"],
  "criticalPoints": [],
  "citations": [
    {
      "chunkId": "chk:...",
      "documentId": "doc:...",
      "title": "ids.ts",
      "sectionTitle": "export function buildSourceId(...)",
      "startLine": 20,
      "endLine": 25
    }
  ],
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
  }
}
```

### 5. `POST /answer/direct`

Sirve para pedir una respuesta directa al modelo sin usar contexto del RAG.

Es util para comparar:
- respuesta sin RAG
- respuesta con RAG

Payload base:

```json
{
  "query": "que es este servicio",
  "model": "openai/gpt-4.1-mini"
}
```

---

### 6. `POST /chat`

Sirve para conversar con un modelo usando:

- contexto bootstrap precargado
- historial reciente de mensajes
- y opcionalmente una consulta adicional al RAG durante la propia conversacion

Payload base:

```json
{
  "message": "y ahora cuales son los siguientes pasos mas naturales?",
  "history": [
    {
      "role": "user",
      "content": "dame un mapa inicial del workspace"
    }
  ],
  "mode": "documental",
  "model": "openai/gpt-4.1-mini",
  "preloadedContext": "<resumen del bootstrap>",
  "allowAdditionalRetrieve": true,
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

---

### 7. `POST /ingest/upload`

Sirve para subir un archivo directamente al backend desde una interfaz web o cliente compatible con `multipart/form-data`.

Es util para:
- PDFs o documentos sueltos
- pruebas rapidas desde el playground
- crear un scope aislado para una carga concreta

Campos esperados del formulario:

- `file`
- `sourceId` opcional
- `mode`
- `tags`

Si se usa `sourceId`, el archivo subido no se mezcla con otros scopes salvo que elijas reutilizar ese mismo identificador.

---

### 8. `GET /logs/recent`

Devuelve los logs recientes de evaluacion guardados por el sistema.

Sirve para revisar:
- consultas con contexto insuficiente
- respuestas problemáticas
- logs manuales marcados por el usuario

Ejemplo:

```bash
curl -sS "https://rag.por-correo.com/logs/recent"
```

---

### 9. `POST /logs/manual`

Permite registrar manualmente una consulta o respuesta que quieras revisar despues.

Es util cuando:
- la respuesta no te convence
- detectas una carencia del RAG
- quieres dejar una nota humana asociada a una consulta

Payload base:

```json
{
  "operation": "answer",
  "reason": "manual_review_requested",
  "query": "prueba de log manual",
  "mode": "documental",
  "intent": "specific",
  "model": "openai/gpt-4.1-mini",
  "note": "la respuesta parece demasiado generica",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

Respuesta esperada resumida:

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

Respuesta esperada:

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

---

## Recomendacion practica para n8n

Si quieres probarlo rapido desde `n8n`:

1. Usa un nodo `HTTP Request`
2. Metodo `POST`
3. URL:

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

o

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

4. Body en JSON
5. Empieza usando `answer` si quieres una respuesta directa
6. Usa `retrieve` si quieres dar el contexto al agente y que el modelo final responda por su cuenta

Payload recomendado para primera prueba en n8n:

```json
{
  "mode": "documental",
  "intent": "specific",
  "query": "que tenemos pendiente por hacer en este workspace",
  "scope": {
    "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
  }
}
```

---

## Nota importante

El `scope` es clave para no mezclar fuentes distintas.

Ejemplos de `scope` utiles:

- documentacion global del workspace:

```json
{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/docs"
}
```

- documentacion del modulo RAG:

```json
{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/docs"
}
```

- codigo del modulo RAG:

```json
{
  "sourceRef": "/home/pancho/Documentos/Empresa/Desarrollo/IA/RAG/src"
}
```

---

## Siguiente evolucion natural

Mas adelante esta API podra exponerse tambien mediante un `MCP`, pero a dia de hoy ya puede consumirse directamente por HTTP desde:

- modelos
- agentes
- flujos de `n8n`
- aplicaciones propias