254 lines
20 KiB
Markdown
254 lines
20 KiB
Markdown
# 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.
|
|
|
|
- [x] 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.
|
|
- [x] 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`](./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`](./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.
|