rag-service/docs/OPERATIVA.md

# Operativa del servicio RAG

**Modulo:** RAG
**Ultima actualizacion:** 2026-09-21
**Version:** 1.3

---

Este documento registra los hechos operativos del servicio RAG: la configuracion vigente en EasyPanel y la salida por etapas del OCR. No contiene secretos: las credenciales reales viven unicamente en EasyPanel.

## Estado verificado (2026-09-17)

- `KNOWLEDGE_LIFECYCLE_ENFORCED=true`: el ciclo de vida del conocimiento esta activo; no queda pendiente ninguna activacion.
- `OCR_INGEST_ENABLED=true`: la ingesta OCR esta habilitada en el RAG desplegado.
- `OCR_SERVICE_URL`: configurada hacia el servicio privado `ocr-service` de la red interna.
- `OCR_INTERNAL_TOKEN`: secreto compartido configurado en EasyPanel (RAG y servicio OCR); su valor nunca se documenta.
- Volumen duradero del RAG en `/data/ingestions`: conserva originales y artefactos de revision.
- Volumen transitorio del OCR en `/data/jobs`: cola SQLite y trabajos en curso.
- La respuesta publica sin token de una ruta OCR protegida es `401`, lo que confirma que el proceso desplegado tiene OCR habilitado. Con OCR deshabilitado, la misma ruta responderia `404` antes de autenticar.
- El estado mostrado en EasyPanel debe contrastarse con su entorno persistido y con el entorno del contenedor en ejecucion; anteriormente la UI mostro valores distintos por variables duplicadas y desfasadas.
- `GET /health` del RAG confirma PostgreSQL, Qdrant y reconciliador sanos. OCR responde internamente `live=ok` y `ready=true`, con cola vacia y version `0.1.0`.
- La migracion `003_ocr_recovery_audit.sql` esta aplicada y su tabla de auditoria existe.
- Las rutas autenticadas de revision y recuperacion devuelven errores estructurados y seguros para una candidata inexistente: `404`, `OCR_CANDIDATE_NOT_FOUND` y accion `verify_version_id`.
- La candidata OCR heredada de FacturaTech v4 fue cerrada como `failed` el 2026-09-20 mediante recuperacion administrativa auditada tras confirmar `OCR_ARTIFACT_UNAVAILABLE`. No fue indexada ni activada; la fuente conserva su version activa y no tiene candidatas OCR bloqueantes.
- Las imagenes en ejecucion tienen digest, pero ambas etiquetas OCI `org.opencontainers.image.revision` valen `unknown`: EasyPanel no esta pasando `BUILD_REVISION` durante el build. La identidad de revision verificable sigue pendiente.

## Proxima version preparada

- RAG y OCR `0.2.0` estan preparados localmente; produccion sigue en `0.1.0` hasta ejecutar el despliegue.
- Ambas imagenes publican `org.opencontainers.image.version` y `org.opencontainers.image.revision`; las respuestas de salud muestran `version` y `revision`.
- EasyPanel debe construir ambas imagenes con `RAG_VERSION=0.2.0` u `OCR_VERSION=0.2.0` y `BUILD_REVISION=<commit desplegado>`.
- Por decision del usuario, RAG y OCR se despliegan juntos con `OCR_INGEST_ENABLED=true`. El despliegue por etapas queda reservado para diagnosticar un fallo cuyo origen no sea claro.

## Lista rapida en EasyPanel

1. Rotar las credenciales expuestas (ver seccion siguiente); la rotacion sigue pendiente.
2. Comprobar que las variables coinciden con la tabla de configuracion actual.
3. Mantener `OCR_INGEST_ENABLED=true` para el flujo OCR ya habilitado.
4. Pulsar `Deploy` en EasyPanel despues de cada cambio principal.
5. Verificar `GET /health` del RAG y las rutas internas de salud del OCR tras cada deploy.
6. Registrar el digest de cada imagen y confirmar que `version` y `revision` coinciden con la entrega desplegada.

## Accion de seguridad urgente: rotar credenciales

Credenciales reales quedaron expuestas en una conversacion de chat. Hay que rotarlas:

- La credencial de OpenRouter (variable `EMBEDDING_API_KEY`; y `ANSWER_API_KEY` si tiene valor propio).
- La contrasena y la URL de PostgreSQL (variable `POSTGRES_URL`).
- El token administrativo del ciclo de vida (variable `LIFECYCLE_ADMIN_TOKEN`).

Como hacerlo:

- Generar valores nuevos y actualizarlos unicamente en EasyPanel.
- Este documento no afirma que la rotacion ya se haya realizado.
- Nunca pegar valores de credenciales en chat, documentacion, historial ni ficheros versionados.

## Como se despliega

- Tras cada cambio principal (variables de entorno o codigo nuevo subido por Git), el usuario pulsa el boton `Deploy` de EasyPanel.
- No existe ninguna accion automatizada documentada sobre EasyPanel: ni scripts, ni comandos de panel, ni webhooks. El deploy siempre lo dispara una persona desde el panel.
- Verificacion minima tras cada deploy: `GET /health` del RAG.

## Configuracion actual (valores no secretos)

Valores vigentes confirmados en produccion (2026-09-17):

| Variable | Valor actual |
|---|---|
| `NODE_ENV` | `production` |
| `PORT` | `80` |
| `QDRANT_URL` | `http://qdrant:6333` |
| `QDRANT_API_KEY` | vacia (sin valor) |
| `QDRANT_COLLECTION` | `rag_chunks` |
| `EMBEDDING_PROVIDER` | `openrouter` |
| `EMBEDDING_MODEL` | `qwen/qwen3-embedding-8b` |
| `EMBEDDING_BASE_URL` | `https://openrouter.ai/api/v1` |
| `ANSWER_PROVIDER` | `openrouter` |
| `ANSWER_MODEL` | `openai/gpt-4.1-mini` |
| `ANSWER_BASE_URL` | `https://openrouter.ai/api/v1` |
| `POSTGRES_SSL` | `false` |
| `KNOWLEDGE_LIFECYCLE_ENFORCED` | `true` |
| `INGEST_WRITES_ENABLED` | `true` |
| `OCR_INGEST_ENABLED` | `true` |
| `OCR_SERVICE_URL` | configurada hacia el servicio privado `ocr-service` |

Notas de comportamiento (derivadas del codigo, sin secretos):

- Si `ANSWER_API_KEY` no se define, el codigo reutiliza `EMBEDDING_API_KEY`.
- Si `POSTGRES_URL` no se define, el codigo prueba `DATABASE_URL`.
- Si `OCR_INGEST_ENABLED` no existe, el codigo tambien la toma como `false`; por eso debe existir explicitamente con valor `true` en el entorno persistido de EasyPanel.
- Un cambio en `KNOWLEDGE_LIFECYCLE_ENFORCED`, `INGEST_WRITES_ENABLED` o `OCR_INGEST_ENABLED` se hace siempre en EasyPanel y se registra en este documento.

## Variables con secretos

Estas variables contienen credenciales reales. Aqui solo se registran sus nombres:

| Variable | Estado |
|---|---|
| `EMBEDDING_API_KEY` | Configurada en EasyPanel; nunca copiarla en documentacion. |
| `ANSWER_API_KEY` | Configurada en EasyPanel; nunca copiarla en documentacion. |
| `POSTGRES_URL` | Configurada en EasyPanel; nunca copiarla en documentacion. |
| `LIFECYCLE_ADMIN_TOKEN` | Configurada en EasyPanel; nunca copiarla en documentacion. |
| `OCR_INTERNAL_TOKEN` | Configurada en EasyPanel, compartida con el servicio OCR y enviada como `Authorization: Bearer`; nunca copiarla en documentacion. |

## Salida por etapas del OCR

El OCR es un servicio privado e independiente. El RAG solo lo llama si `OCR_INGEST_ENABLED` esta activo; con el flag apagado, la ingesta sigue el flujo nativo actual, sin cambios. Hoy el flag esta en `true` en el RAG desplegado.

### Servicio OCR privado (referencia de configuracion)

- Contenedor `ocr-service`, imagen Python CPU con PaddleOCR `3.4.0` y PaddlePaddle `3.2.2`.
- Una sola replica y un solo worker; limites del servicio: maximo 3 CPU y 5 GiB de RAM.
- Modelos descargados durante el build, nunca en el arranque.
- Solo red interna del proyecto (`easypanel-ia_servicios`), sin dominio publico.
- `OCR_SERVICE_URL` apunta al servicio OCR interno por el puerto `8000`; el valor por defecto del codigo es `http://ocr-service:8000`, valido para un servicio llamado `ocr-service` en la red interna.
- Limites fijos (no configurables por variables): cola de 3 trabajos, concurrencia 1, render a 200 DPI, maximo 50 MiB por PDF y 100 paginas por trabajo.
- Cada trabajo dispone de un lease y un limite total de 15 minutos. Solo se recupera una vez; la segunda interrupcion o el timeout son terminales.
- La readiness es falsa hasta que modelo, worker, sweeper y almacenamiento estan operativos; expone conteos por estado, recuperaciones y ultima limpieza sin incluir secretos. El healthcheck de arranque concede 90 segundos.

### Volumenes

| Volumen | Ruta | Papel |
|---|---|---|
| Duradero del RAG | `/data/ingestions` | Originales y artefactos de revision conservados. |
| Transitorio del OCR | `/data/jobs` | Cola SQLite, PDFs y resultados en curso. |

### Limpieza transitoria del OCR

- Las filas transitorias, el PDF y los resultados del OCR se eliminan tras la transferencia duradera al RAG, cuando el resultado es aceptado.
- Si esa transferencia no llega, un sweeper ejecutado al arrancar y cada 15 minutos expira los trabajos a las 24 horas, hace checkpoint WAL y vacuum incremental.
- Antes de admitir el PDF y antes de publicar cada PNG, OCR limita su uso al menor entre 10 % del filesystem y 2 GiB, reservando libre el mayor entre 10 % y 2 GiB. La presion falla cerrada como `OCR_STORAGE_PRESSURE`.
- La limpieza transitoria nunca toca los artefactos duraderos del RAG ni el corpus activo.

### Verificacion posterior al despliegue (cuando cambian ambos servicios)

1. Publicar el codigo en Git `main` y desplegar juntos OCR y RAG `0.2.0` desde EasyPanel con `OCR_INGEST_ENABLED=true`.
2. Verificar el OCR internamente: `GET /health/live` y `GET /health/ready` deben responder con el servicio preparado.
3. Verificar `GET /health` del RAG: PostgreSQL, Qdrant y reconciliador deben estar correctos.
4. Comprobar una ruta OCR protegida sin token. Un `401 Lifecycle admin token is required` confirma que OCR esta habilitado y que la autenticacion administrativa permanece protegida; no es un error que requiera correccion.
5. Contrastar `OCR_INGEST_ENABLED=true` en el entorno persistido de EasyPanel y en el proceso del contenedor si la UI no coincide con el comportamiento efectivo.
6. Consultar con token administrativo una version inexistente en revision y recuperacion: ambas deben devolver un error estructurado `404 OCR_CANDIDATE_NOT_FOUND` sin modificar datos.
7. Confirmar que `rag_schema_migrations` contiene `003_ocr_recovery_audit.sql` y que existe `rag_ocr_recovery_audit`.
8. Revisar los digests y confirmar que las etiquetas OCI y las respuestas de salud muestran `0.2.0` y el commit desplegado, no `unknown`.
9. Tras completar estas comprobaciones, crear una candidata FacturaTech no activa. No aprobar, indexar ni activar hasta presentar la evidencia al usuario y recibir autorizacion explicita.

### Rollback de emergencia

- Ante cualquier fallo: poner `OCR_INGEST_ENABLED=false`, pulsar `Deploy` en el RAG y conservar la version activa actual del corpus.
- El sistema es fail-closed: un fallo del OCR deja intacta la version activa anterior; no hay activacion parcial.
- Las paginas con OCR no se activan solas; requieren revision humana obligatoria (estado `review_required`).
- Desactivar el OCR no borra el corpus activo ni exige reingesta.

### Limites opcionales del RAG (valores por defecto del codigo)

| Variable | Valor por defecto |
|---|---|
| `OCR_MAX_UPLOAD_BYTES` | `52428800` (50 MiB) |
| `OCR_MAX_PAGES` | `100` |
| `OCR_PAGE_TIMEOUT_MS` | `60000` |
| `OCR_TOTAL_TIMEOUT_MS` | `900000` (15 min) |
| `LIFECYCLE_RECONCILE_INTERVAL_MS` | `300000` |
| `LIFECYCLE_INDEXING_STALE_TIMEOUT_MS` | `1800000` |
| `QDRANT_LOGS_COLLECTION` | `rag_eval_logs` |

## Verificaciones habituales

- `GET /health` del RAG: estado general con PostgreSQL, Qdrant y reconciliador.
- `GET /health/live` y `GET /health/ready` del servicio OCR: solo accesibles desde la red interna del proyecto.
- Tras cambiar cualquier variable: pulsar `Deploy` y verificar `/health`.

## Reglas de uso de este documento

- Consultarlo antes de tareas con servicios externos, credenciales, despliegues o ejecuciones recurrentes.
- Nunca escribir secretos aqui: solo nombres de variables y donde viven (EasyPanel).
- Si un hecho operativo deja de ser valido, actualizarlo o marcarlo como obsoleto en la misma intervencion en que se descubra.