rag-service/docs/PENDIENTES_RAG.md

Pendientes priorizados del RAG

Ultima actualizacion: 2026-09-13 Responsable de la priorizacion: Usuario
Estado: Activo

Este documento es la fuente canonica del orden de trabajo pendiente del modulo RAG. La numeracion ya refleja la prioridad final indicada por el usuario.

1. Documentacion y descubrimiento de la API

Estado: Completado y validado definitivamente en produccion el 2026-09-08.

• Implementar /help o una especificacion OpenAPI consultable.
• Actualizar documentos desfasados que todavia muestran como pendientes funciones ya desplegadas, como playground, logs y cleanup.
• Documentar los contratos, parametros, respuestas y errores reales de todos los endpoints.
• Mantener la documentacion alineada con produccion para que agentes e integradores no tengan que reconstruir el comportamiento desde el codigo.

2. Ciclo de vida del conocimiento

Estado: Completado y validado en produccion el 2026-09-13.

El contrato de implementacion esta cerrado en CONTRATO_CICLO_VIDA_Y_OCR.md. Antes de ejecutar las pruebas de migracion o activar el ciclo de vida hay que completar este prerrequisito:

Prerrequisito bloqueante: preparar PostgreSQL

• Confirmar que existe la instancia y la base de datos que usara RAG en EasyPanel.
• Obtener el hostname interno, puerto, nombre de base de datos, usuario y requisitos SSL.
• Configurar POSTGRES_URL, POSTGRES_SSL y LIFECYCLE_ADMIN_TOKEN en el servicio RAG.
• Ejecutar las migraciones del esquema y verificar las tablas, permisos y SELECT 1 desde RAG. Completado el 2026-09-13.
• Revisar que no falten variables, red interna, credenciales, almacenamiento persistente o permisos de migracion. Completado el 2026-09-13; la configuracion completa de backups queda diferida al paquete del punto 7.
• Inventariar las fuentes actuales de Qdrant y preparar su carga en el catalogo PostgreSQL.

Resultado del dry-run legacy

• Ejecutado el 2026-09-13 sin --apply.
• Detectados 22.605 puntos en 7 fuentes de rag_chunks.
• ok: true; no se encontraron blockedReasons.
• Ventana de mantenimiento ejecutada con INGEST_WRITES_ENABLED=false y rag_system_state.maintenance=true.
• Migracion aplicada con el lote 17f05cae-c5a7-49a5-b3ad-729958e1a342 usando snapshot Qdrant remoto con checksum a55b13d3b6b791e9b148f87491b9b2788ce5797ee997a9f6be2a6d424eb92302.
• Catalogadas 7 fuentes y 22.605 puntos; todas las versiones quedaron active y sus recuentos PostgreSQL/Qdrant coinciden.
• KNOWLEDGE_LIFECYCLE_ENFORCED=true, INGEST_WRITES_ENABLED=true, maintenance=false y retrieval validado en produccion.

El punto 2 queda cerrado. El punto 3, OCR integrado en la ingesta, puede comenzar respetando el contrato secuencial.

• Crear un catalogo de fuentes y versiones ingeridas.
• Saber que documento esta vigente, obsoleto, reemplazado o pendiente de reingesta.
• Evitar duplicados y permitir actualizaciones incrementales controladas.
• Registrar fecha de indexacion, modelo de embeddings, proveedor y version del contenido.
• Facilitar el reemplazo o rollback de una fuente sin depender de operaciones manuales dificiles de auditar.

Paquete de mejora posterior: seguimiento del corpus en API y frontend

Prioridad: Diferida, sin urgencia; no bloquea la preparacion de PostgreSQL ni el cierre funcional del punto 2. Retomar al trabajar en el frontend de gestion.

• Exponer por API los documentos que componen cada version de una fuente.
• Exponer el historial de intentos de ingesta, resultados y errores.
• Incluir fechas y detalles de error de las versiones en las respuestas de la API.
• Ampliar la vista basica del playground a una gestion de fuentes, documentos, versiones e ingestas con su estado e historial.
• Incorporar al frontend las operaciones ya disponibles por API: activacion, rollback, reintento y purga.

3. OCR integrado en la ingesta

Diseño: Contrato de implementacion cerrado en CONTRATO_CICLO_VIDA_Y_OCR.md. El punto 2 ya fue validado en produccion; su ejecucion queda habilitada.

• Detectar PDFs con capturas, imagenes o una capa textual insuficiente.
• Ejecutar OCR automaticamente o bloquear la ingesta para revision cuando no pueda garantizarse la cobertura.
• Generar un documento intermedio auditable cuando sea necesario.
• Verificar el resultado antes de sustituir una fuente vigente.
• Evitar que se repita el problema detectado con el PDF de FacturaTech.

4. Mejora del retrieval

• Anadir busqueda hibrida semantica y textual para codigos exactos como FAT07, 504 o SQLSTATE[23505].
• Mejorar el ranking usando coincidencias de codigo, regla, modulo y mensaje, no solo proximidad semantica.
• Crear un conjunto estable de consultas de evaluacion basado en casos reales.
• Medir precision, resultados irrelevantes y consultas ambiguas.
• Refinar retrieval y chunking con evidencia de uso, no mediante cambios generales sin medicion.

5. Seguridad de la API

• Anadir autenticacion para consumidores autorizados.
• Proteger especialmente uploads, cleanup y operaciones sobre logs.
• Aplicar rate limiting y limites de tamano o tipo de archivo.
• Revisar CORS, exposicion publica, registros sensibles y permisos por operacion.
• Sustituir la configuracion sin credenciales de n8n cuando exista el mecanismo de autenticacion definitivo.
• Actualizar Express/qs para cerrar los avisos moderados pendientes de npm audit.

6. Pruebas automatizadas

• Incorporar un framework y scripts de pruebas; actualmente el proyecto no tiene suite automatizada.
• Cubrir ingesta, parsing, chunking, scopes, cleanup y retrieval.
• Probar contratos y respuestas de error de la API.
• Anadir pruebas de regresion con consultas reales como las validadas para FacturaTech.
• Separar pruebas unitarias, de integracion y verificaciones opcionales contra servicios remotos.

7. Operacion y mantenimiento

• Resolver la colision de sourceRef al ingerir carpetas homonimas.
• Separar claramente configuracion versionable y secretos locales.
• Verificar y cerrar documentalmente la migracion del repositorio raiz de RAG y su despliegue en EasyPanel.
• Revisar copias temporales o backups asociados a la migracion antes de eliminarlos.
• Mantener un procedimiento fiable de despliegue, verificacion y rollback.

Paquete de mejora posterior: backups manuales del RAG

Prioridad: Diferida, sin urgencia; no bloquea la preparacion actual de PostgreSQL. Sin programacion automatica.

Estado de la propuesta: Diseno guardado para completar e implementar mas adelante.

• Configurar el destino de backups y diagnosticar el error observado al crearlo en EasyPanel.
• Preparar copias manuales de la nueva base del RAG y snapshots de Qdrant; db_gestion_flujos_n8n es ajena a este alcance.
• Definir una ventana sin escrituras para obtener copias coherentes de ambos almacenes.
• Documentar y comprobar la restauracion, incluyendo la recuperacion de los permisos necesarios.
• Este paquete difiere la solucion habitual de backups; el snapshot previo exigido por la migracion legacy sigue formando parte de esa operacion.

Diseno propuesto

• Mantener los datos primarios separados: PostgreSQL conserva el catalogo, Qdrant conserva chunks y embeddings, y un volumen privado del RAG conserva originales y artefactos.
• Montar un volumen rag-ingestions en /data/ingestions para conservar originales, manifiestos y futuros artefactos OCR por version.
• Cambiar la ingesta para guardar el original antes de procesarlo; el flujo actual usa /tmp y elimina los uploads al terminar.
• Respaldar PostgreSQL con un dump portable de db_rag y, cuando quede configurado, con Database Backups de EasyPanel hacia un destino S3-compatible.
• Respaldar Qdrant con snapshot de la coleccion o del almacenamiento completo, preferentemente hacia el mismo destino externo.
• Incluir los artefactos del volumen en el plan de backup y probar una restauracion completa antes de considerar portable el servicio.
• No tratar un volumen Docker del mismo VPS como backup externo: protege frente a reinicios, no frente a perdida del servidor.
• Mantener fuera de este alcance db_gestion_flujos_n8n.

8. Sistema de evaluacion

• Revisar periodicamente los logs de evaluacion almacenados en Qdrant.
• Convertir incidencias reales en casos de prueba permanentes.
• Anadir metricas de recuperacion, calidad y contexto insuficiente.
• Mantener trazabilidad entre una incidencia, el cambio aplicado y la validacion posterior.
• Diferenciar claramente observacion manual, alerta automatica y regresion confirmada.

9. Capa MCP

• Exponer capacidades del RAG como tools MCP reutilizables.
• Definir inicialmente retrieval y consulta de fuentes; limitar operaciones destructivas.
• Mantener HTTP como API base y MCP como adaptador, evitando duplicar la logica del servicio.
• Definir autenticacion, contratos y permisos antes de exponer operaciones adicionales.

10. Modelo de answer

• Evaluar y sustituir openai/gpt-4.1-mini por el modelo definitivo de respuesta.
• Comparar calidad, coste, latencia y dependencia del proveedor.
• Mantener answer construido sobre retrieve y evitar un segundo camino de recuperacion.
• Considerar esta tarea despues de las anteriores; integraciones como WhatsApp ya pueden usar /retrieve y dejar la respuesta final a su propio agente.

Regla de mantenimiento

• No cambiar este orden sin confirmacion del usuario.
• Al completar un punto, registrar evidencia y marcar su estado sin renumerar silenciosamente los demas.
• Las tareas detalladas pueden vivir en documentos independientes, pero este archivo conserva la prioridad global del modulo.