rag-service/docs/PENDIENTES_RAG.md

Pendientes priorizados del RAG

Ultima actualizacion: 2026-09-23 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.

Hoja de ruta OCR prioritaria

Esta secuencia tiene prioridad sobre la aceptacion productiva pendiente de FacturaTech. No cerrar v4, crear una candidata nueva, reingestar FacturaTech, aprobar, indexar ni activar contenido fuera del orden indicado.

Fase 1. Corregir y verificar el codigo

Estado: Completada funcionalmente y verificada en produccion el 2026-09-17.

1. Completado: errores OCR estructurados, seguros y accionables.
2. Completado: recuperacion administrativa autenticada y auditada para candidatas con evidencia invalida.
3. Completado: RAG y OCR exponen versiones; los digests identifican las imagenes desplegadas.
4. Completado: errores, recuperacion, reinicios y versiones cubiertos localmente y verificados en produccion sin modificar v4.

Salida: el comportamiento nuevo esta validado y v4 permanece intacta. La etiqueta OCI de revision legible sigue como mejora operativa no bloqueante: actualmente el digest es la identidad verificable de la imagen.

Fase 2. Resolver la candidata v4

Estado: Completada en produccion el 2026-09-20, con aprobacion explicita del usuario.

1. Completado: v4 respondio 409 OCR_ARTIFACT_UNAVAILABLE y accion use_admin_recovery mediante el contrato autenticado.
2. Completado: confirmada la ausencia de la evidencia durable necesaria para su revision.
3. Completado: recuperacion administrativa auditada aplicada sobre la unica candidata heredada.
4. Completado: v4 quedo en estado failed, no activa, sin indexacion ni activacion; la fuente conserva su version activa.
5. Completado: no quedan candidatas pending, indexing ni review_required que bloqueen la fuente.

Salida: v4 queda resuelta de forma auditable como failed, sin crear otra candidata.

Fase 3. Hardening OCR y aceptacion de FacturaTech

Estado: 0.2.0 desplegada y D1-D4 verificados en produccion. La aceptacion v6-v7 encontro dos defectos correctivos; queda bloqueada hasta entregar 0.2.1 segun el anexo del contrato.

La candidata v5 5f2317c6-7a8a-4e08-a614-f8189602ebb8 completo 25/25 paginas OCR, pero fallo despues cuando RAG solicito 25 imagenes de revision en paralelo. El rerender concurrente provoco un SIGSEGV de PDFium/FreeType, salida 139 y reinicio del contenedor; no hubo OOM. La candidata quedo fallida y la version activa no cambio.

Fase 3A. Hardening del runtime

1. Completado localmente: cola SQLite durable con un unico worker real y recuperacion tras reinicio.
2. Completado localmente: PNG privados durante el render inicial y servicio desde fichero sin volver a ejecutar PDFium.
3. Completado localmente: transferencia RAG secuencial, idempotente y reanudable mediante comprobantes privados por pagina.
4. Completado localmente: exclusion mutua defensiva de PDFium y cierre determinista de recursos.
5. Completado localmente: observabilidad segura, limites de cola/tiempo/disco, recuperacion por lease, sweeper periodico y vacuum incremental.
6. Completado: validacion independiente con PDF real de 25 paginas, reinicio durante el trabajo, concurrencia, reanudacion, ausencia de duplicados y limpieza cuantitativa.

Fase 3B. Aceptacion productiva

Estado: Ejecutada y no superada. v6 fallo por colision idempotente con un trabajo terminal ocr-v1. Tras la limpieza automatica, v7 proceso 25/25 paginas y persistio 25 PNG validos, pero un falso negativo de p10Confidence la cerro como OCR_QUALITY_BLOCKED. Las 34 entradas estan presentes; FAT07, NSAV06 y DSAU04 requieren correccion humana por confusion 0/o. La version activa no cambio.

1. Completado: desplegados juntos OCR y RAG 0.2.0 con revision verificable.
2. Completado: candidatas v6 y v7 creadas con activate=false; ninguna fue indexada ni activada.
3. Completado: evidencia durable de v7, 25 imagenes y 34 entradas verificadas.
4. No superado: la puerta de calidad impidio llegar a revision y dos de los cuatro codigos criticos no son exactos antes de correccion humana.
5. Completado: version activa anterior confirmada intacta.

Fase 3C. Correccion post-aceptacion 0.2.1

Estado: R1-R4 completados y verificados localmente. R5 centraliza 0.2.1 en VERSION; RAG, OCR, health, OpenAPI, etiquetas OCI y builds rechazan valores declarados divergentes. La validacion local completa ya paso: imagen OCR construida con PaddleOCR/PaddlePaddle y modelos baked, health real correcto, suite Python en imagen y suite Node correctas. El fixture autocontenido de 25 paginas valida advertencias p10, 25 PNG y candidata revisable; las caidas en cada frontera de persistencia se recuperan exactamente una vez y los diagnosticos administrativos no exponen errores internos. La migracion 004 se valido con historial 001-003 y una fila historica en PostgreSQL Docker local aislado; el contenedor reutilizable quedo detenido. R5 permanece bloqueada hasta autorizacion explicita de despliegue conjunto. Contrato completo en CONTRATO_CICLO_VIDA_Y_OCR.md, anexo "Hallazgos productivos v6-v7".

1. Completado localmente: R1, identidad ocr-v2 completa, acknowledgement de los cuatro estados, recuperacion posterior a succeeded sin reenviar OCR y rechazo fail-closed de respuestas incompatibles.
2. Completado localmente: R2, p10Confidence bajo aislado como advertencia, bloqueos reales preservados y diagnostico determinista por pagina.
3. Completado localmente: R3, migracion 004 preparada sin aplicar, cadena de hashes durable, quality-report.json privado e inmutable y diagnostico seguro.
4. Completado localmente: R4, suites, revision independiente, fixture autocontenido de 25 paginas, simulaciones de recuperacion tras cada frontera de persistencia y hardening de errores administrativos. 004 se aplico mediante el runner en PostgreSQL Docker local aislado despues de controlar 001-003; se verificaron la fila historica, columnas, restriccion, historial 001-004 e idempotencia. El contenedor reutilizable queda detenido; nunca se uso EasyPanel ni produccion.
5. Pendiente: R5, consumir 0.2.1 desde un unico VERSION, validar igualdad de health y etiquetas OCI, desplegar y probar RAG/OCR como una unica operacion y repetir aceptacion no activa con revision humana.

Checklist ejecutable de R5

Retomar esta lista en orden despues de la compactacion. No iniciar acciones productivas antes de completar la preparacion local y obtener la autorizacion correspondiente.

• Crear VERSION en la raiz con 0.2.1 y convertirlo en la unica fuente de version para RAG, OCR, health, pruebas y builds; cualquier version duplicada o divergente debe fallar.
• Ejecutar la validacion local completa de RAG, OCR e imagenes y actualizar la documentacion afectada.
• Revisar el worktree, crear un unico commit de entrega y hacer push a main; RAG y OCR deben publicarse desde ese mismo commit.
• Antes del despliegue, identificar explicitamente la base y el entorno productivos, revisar rag_schema_migrations y confirmar que solo estan pendientes las migraciones esperadas.
• Configurar en ambos servicios BUILD_REVISION=<commit publicado> y mantener OCR_INGEST_ENABLED=true.
• Desplegar RAG y OCR desde el mismo commit como una unica operacion en EasyPanel; no considerar completada la entrega hasta que ambos terminen.
• Verificar conjuntamente version=0.2.1, revision, etiquetas OCI, digests, migracion 004, health, cola OCR, almacenamiento, PostgreSQL, Qdrant y reconciliador.
• Confirmar el estado auditado de v7 sin aprobarla, indexarla ni activarla.
• Crear una candidata nueva de FacturaTech con activate=false y supervisarla hasta review_required o fallo.
• Ejecutar la revision humana de las 34 entradas y los cuatro codigos criticos; registrar IDs, estados, recuentos, hashes, versiones, revisiones y digests.
• Solicitar autorizacion separada antes de aprobar o indexar y una confirmacion adicional antes de activar.

Si aparece un fallo real cuyos sintomas justifiquen aislar servicios, valorar entonces OCR_INGEST_ENABLED=false y el despliegue por etapas. No aplicar ese modo preventivamente.

Regla de despliegue: R1-R4 no despliegan ni prueban produccion. Solo R5 puede desplegar; RAG y OCR se despliegan juntos con OCR_INGEST_ENABLED=true y la entrega no se considera completada hasta que ambos coincidan en version/revision y superen juntos la bateria de salud. No se desactiva OCR ni se despliega por etapas de forma preventiva: ese modo queda reservado para un fallo real cuyos sintomas justifiquen aislar un servicio. BUILD_REVISION sigue manual para esta entrega y se contrasta con el commit; los digests son la identidad exacta. No se introduce CI, registry ni automatizacion de EasyPanel sin aprobacion separada.

Regla PostgreSQL de R4: no usar la base configurada en EasyPanel ni cargar los ficheros locales que contienen sus secretos. Usar un contenedor local aislado y reutilizable, pasar una URL local solo al proceso de prueba y comprobar la secuencia de migraciones. El contenedor conserva su volumen para futuras pruebas, no tiene reinicio automatico y debe quedar detenido al terminar para que PostgreSQL no consuma CPU ni RAM activa. No apagar ni limpiar Docker globalmente. El runner aplica todas las migraciones pendientes. La aplicacion de 004 en produccion pertenece a R5 y necesita autorizacion explicita independiente.

Evidencia: las pruebas automatizadas deben ser autocontenidas. La comparacion con el documento manual de FacturaTech es evidencia externa y se registra como tal, separada del PASS automatizado. R5 debe dejar IDs, estados, recuentos, hashes, versiones, revisiones y digests suficientes para auditar la aceptacion sin depender de memoria conversacional.

El SDD ocr-ingest-integration se archiva con 29/30 tareas completas y 7.4 incompleta. La continuidad del hardening y de la aceptacion se controla mediante el contrato ODD canónico, sin declarar retrospectivamente superada la aceptacion fallida.

Salida: 0.2.1 supera los criterios del anexo, FacturaTech alcanza review_required con evidencia completa y solo se aprueba o activa con autorizacion explicita.

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.

Paquete de mejora posterior: OCR reutilizable para entradas visuales

Prioridad: Diferida; no bloquea la correccion actual ni la aceptacion de FacturaTech.

• Mantener el contrato actual de trabajos PDF.
• Aceptar directamente image/jpeg y image/png, ademas de PDF.
• Normalizar cada entrada visual a un resultado por pagina con texto, lineas, posiciones y metricas.
• Emitir resultados OCR o errores estructurados sin depender del RAG.
• Mantener RAG como consumidor opcional del OCR y responsable de versionado, revision e indexacion de conocimiento.
• Definir limites de tamano, dimensiones y paginas, autenticacion, retencion y pruebas para cada formato.

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.