Fase 2 – Gemelo Operativo Prodisys

.. contents:: Tabla de contenido :depth: 2 :local:

Resumen ejecutivo

Prodisys requiere un gemelo operativo que apoye el diseño y desarrollo de equipos (hidrociclones, aeroenfriadores, eductores) sin quedar acoplado a una interfaz única. Esta fase prioriza desacoplar la lógica de cálculo en un núcleo de dominio reutilizable, automatizar un pipeline de simulación e informes, y habilitar capacidades de búsqueda técnica y trazabilidad para acelerar diseño, validación y presentación a cliente.

Resumen visual de hitos de la Fase 2

Mes

Hito principal

Entregable

Responsable

1

Desacople del núcleo de cálculo

Librerías prodisys.core y prodisys.calc

Ingeniería

2

Pipeline OpenFOAM y generación de informes

Pipeline YAML y plantillas .rst→PDF

Simulación / Ingeniería

3

Integración UI y exportación comercial

CLI funcional, paquete Aleph

Ingeniería / Comercial

4

Validación y trazabilidad

Tablero de auditoría y checklist de privacidad

Dirección Técnica

(El timeline facilita visualizar la progresión temporal y los entregables clave de la fase 2.)

Objetivos (90 días) — con entregables y métricas de éxito vinculadas

  1. Desacople arquitectónico: extraer el dominio de cálculo en librerías y servicios (CLI/API) reutilizables.

  2. Pipeline de diseño–simulación–informe: de parámetros → mallas → corrida (OpenFOAM) → posproceso → informe .rst/PDF reproducible.

  3. Catálogo de diseños: plantillas parametrizadas con versionado y comparadores de desempeño.

  4. Trazabilidad & auditoría: cada resultado enlazado a insumo, commit, settings y versión de modelo (auditoría JSONL).

  5. Búsqueda técnica: ingesta y extracción de fórmulas, rangos y criterios desde literatura técnica.

  6. Entrega comercial: generación de paquetes (KPIs, gráficas CFD, PDF) para Aleph y publicaciones.

Alcance

  • Familias iniciales: Hidrociclón y Aeroenfriador.

  • Integraciones: OpenFOAM, Git, Aleph.

  • Excluido: control en planta/IoT; futuro.

Arquitectura propuesta (hexagonal)

Capas

  • Dominio: fórmulas, validaciones, criterios. Sin dependencias UI.

  • Aplicación/Servicios: orquestación, pipelines, informes.

  • Adaptadores: UI, CLI, API REST, conectores OpenFOAM/Aleph.

  • Infra: telemetría, almacenamiento, caché.

Patrones clave

  • Ports & Adapters.

  • Pipelines declarativos (YAML).

  • Data Contracts (pydantic).

Mapa de capacidades

Capacidad

Entrada

Salida

Cálculo rápido

YAML/JSON (caudal, D, ρ)

KPIs rápidos (ΔP, eficiencia)

Simulación CFD/CAE

Caso OpenFOAM + geometría STL

Campos, KPIs, imágenes

Comparación multi-escenario

JSONs de resultados

Tablas, gráficos

Generación de evidencia

Parámetros y resultados previos

Informe .rst→PDF

Catálogo & reutilización

Metadatos YAML

Plantillas parametrizadas

Búsqueda técnica

Consulta texto

Resumen con criterios de diseño

Roadmap y entregables

Mes 1 – Extraer core de dominio (prodisys.core, prodisys.calc, prodisys.equipos). CLI mínima. Flujo de bosquejos con YAML.

Mes 2 – Pipeline OpenFOAM (casekit), informes .rst automáticos, catálogo con comparador de resultados.

Mes 3 – Adaptar UI como adaptador, exportación de paquetes comerciales, tablero de auditoría, diálogo de verificación.

Entregables: paquetes Python, CLI, plantillas .rst, catálogo (10–20 escenarios), guía de operación.

Métricas de éxito

  • T2E < 48 h hasta informe PDF.

  • ≥50% de casos nuevos por clon de plantilla.

  • ≥80% de pasos automatizados.

  • Checklist de calidad por caso.

Riesgos y mitigaciones

  • Acoplamiento residual → tests de contrato.

  • Variabilidad de solver → recetas y tolerancias.

  • Gestión de artefactos → convenciones y limpieza.

Repositorio: contenido, acceso y propósito

Contenido: código núcleo (core, calc, equipos, pipelines, adapters, telemetry), interfaces (cli, api, ui_streamlit), plantillas (templates, catalogo, docs), conocimiento (knowledge), automatización (tests, ci).

Acceso: Git privado on-prem (Gitea/GitLab), SSH+2FA, RBAC. Flujo main / develop / feature, MR, tags. Seguridad con Vault y CI sin egress.

Propósito: fuente única de verdad, reproducibilidad (tag+JSONL), desacople, automatización, privacidad, onboarding rápido.

Refactor del repositorio

Estructura objetivo:

prodisys/
  core/
  equipos/
    hidrociclon/
    aeroenfriador/
  calc/
  pipelines/
  adapters/
    ui_streamlit/
    cli/
    api/
    openfoam/
    aleph_export/
  telemetry/
  reports/
  tests/

Mover lógica pura a core/calc, exponer puertos, unificar auditoría (JSONL).

Búsqueda técnica (mínimo viable)

knowledge/ con PDFs y metadatos YAML, indexado y extracción de rangos y criterios de diseño.

Entrenamiento de heurísticas

Feedback explícito (aprobaciones, prioridades) e implícito (uso, selecciones). Ajuste de pesos (λ), reglas go/no-go, ranking multi‑armed bandit, trazabilidad JSONL, modo sandbox y control humano.

Componente cognitivo y estilo de trabajo

Bosquejos: foto → inbox_sketches/, YAML con contexto, objetivos y supuestos. Enlace a ficha de diseño y catálogo.

Extracción: marcaje de cotas, valores con incertidumbre (min/nom/max), heurísticas por familia.

Razonamiento: perfil de decisión (YAML), reglas go/no‑go, diálogo de verificación, justificación.

Aprendizaje: registro de decisiones, evolución de plantillas.

Trazabilidad: auditoría enlaza bosquejo, parámetros, commits y resultados.

Reglas de operación (lenguaje claro y privacidad)

1) Lenguaje claro para no‑sistemas (glosario operativo)

  • Artefacto: cualquier archivo/resultado generado (código, CSV, PNG, informe PDF, malla, caso OpenFOAM, etc.).

  • Pipeline: receta automatizada que toma entradas y produce artefactos (parámetros → malla → simulación → KPIs → informe).

  • YAML: formato de texto legible (listas con guiones y “clave: valor”) para describir pipelines y metadatos.

  • Telemetry/Auditoría: registro cronológico de qué se ejecutó, con qué entradas y qué produjo (trazabilidad/repetibilidad).

  • params.json: archivo de parámetros de entrada en JSON (texto con llaves {}) que consume el pipeline.

  • Adaptador: pieza que conecta el núcleo de cálculo con algo externo (UI, OpenFOAM, Aleph) sin romper el núcleo.

  • Dominio: parte de ingeniería pura (fórmulas, criterios, validaciones) sin UI ni dependencias externas.

  • CLI: ejecutar desde consola con comandos (p. ej., prodisys run ...).

Apoyos en la UI

  • Tooltips/glosario en línea y botón “¿Qué significa esto?” junto a cada término técnico.

2) Sistema cerrado / privado (sin fuga de datos)

  • Sin terceros por defecto: no se envían documentos ni parámetros a servicios externos (incluidos servicios de IA).

  • Modelos locales: LLM/embeddings on‑prem o infraestructura controlada, sin telemetría saliente.

  • Control de acceso (RBAC): roles (Administrador, Ingeniería, Comercial) y herencia de permisos por artefacto.

  • Cifrado: en reposo y en tránsito; claves en Vault (no en .env plano).

  • Red: política deny‑all egress en contenedores; sólo repos internos y nodos de cómputo autorizados.

  • Auditoría: logs firmados (hash) en logs/agent.log.jsonl + checksum de artefactos; alertas ante salidas de red.

  • Clasificación: INTERNAL, CONFIDENTIAL, CLIENT_CONFIDENTIAL aplicada a todos los artefactos.

  • Backups/retención: snapshots cifrados; retención por clase de dato; derecho al olvido para clientes.

  • Contrato de uso: explícito que ningún gestor de IA externo puede usar datos para entrenamiento.

Pruebas/controles de privacidad

  • Test de circuito cerrado (falla si hay HTTP saliente no autorizado).

  • Escaneo de secretos en CI; bloqueo de commits con credenciales.

  • Revisión periódica de permisos por carpeta/repo.

Siguientes pasos inmediatos

  1. Crear repo prodisys-gemelo.

  2. Extraer paquete prodisys-core.

  3. Especificar pipeline YAML de hidrociclón.

  4. Implementar CLI y prueba e2e.

  5. Definir plantilla .rst y salida PDF.

  6. Activar flujo de bosquejos (inbox_sketches/).

Política de datos y checklist de privacidad

Política de datos (resumen ejecutivo)

  • Toda la información de proyectos y clientes se clasifica como CONFIDENCIAL o CLIENT_CONFIDENTIAL.

  • Ningún artefacto/dataset/documento podrá ser compartido con terceros sin autorización explícita del gerente de ingeniería.

  • Prohibido el entrenamiento, ajuste o inferencia por modelos de IA externos con datos de Prodisys o de clientes.

  • Los datos permanecen bajo control de Prodisys y se procesan únicamente en infraestructura local o controlada.

  • Copias de seguridad cifradas con retención definida (90 días datos temporales, 1 año resultados, indefinido informes finales archivados).

  • Garantizar el derecho al olvido: eliminación completa cuando el cliente lo solicite.

  • Auditorías de cumplimiento al menos cada seis meses.

Checklist de privacidad antes de cada entrega

  1. Clasificación verificada de cada artefacto (INTERNAL/CONFIDENTIAL/CLIENT_CONFIDENTIAL).

  2. Confirmación de cero llamadas externas en pipelines (test de circuito cerrado).

  3. Revisión de hashes/firmas en logs/agent.log.jsonl.

  4. Verificación de que .env no contenga claves expuestas.

  5. Cifrado de backups y permisos por rol vigentes.

  6. Nombres de archivo sin datos personales o nombres de cliente.

  7. Registro de aprobación final de privacidad en auditoría.

Guía de uso paso a paso

Descripción visual paso a paso

Inicio: pantalla de bienvenida con opciones de rol (Administrador, Ingeniería, Comercial).

Caso nuevo: formulario sencillo con campos para nombre, tipo de equipo y carga del bosquejo.

Ficha de diseño: vista de formulario con pestañas para contexto, variables y prioridades.

Preguntas inteligentes: cuadro de diálogo guiado con opciones y respuestas rápidas.

Resultados preliminares: tablero con KPIs y visualizaciones.

Pipeline en ejecución: barra de progreso y estado de cada etapa (malla, simulación, posproceso, informe).

Informe: previsualización en PDF con opción de exportar a paquete comercial.

Catálogo: vista de tarjetas con miniaturas de casos anteriores y filtros por equipo o cliente. — tiempos estimados e intervención — tiempos estimados e intervención

  1. Entrar y crear un caso — 1–2 min · Intervención: baja

    • Inicia sesión y elige tu rol (Administrador / Ingeniería / Comercial).

    • Crea un Caso (expediente de diseño): nombre, objetivo, familia de equipo.

    • Sube el bosquejo (foto) que irá a inbox_sketches/.

  2. Ficha de diseño (traducción sencilla) — 3–6 min · Intervención: media

    • Completa contexto, supuestos y criterios de éxito.

    • El sistema guarda metadatos en YAML (texto “clave: valor”).

    • Ajusta tu Perfil de decisión (seguridad, eficiencia, costo, mantenibilidad, plazos).

  3. Preguntas inteligentes del gemelo — 2–4 min · Intervención: baja

    • 5–7 preguntas cortas para aclarar ambigüedades (p. ej., “¿L/D objetivo?”, “¿ΔP máxima?”).

    • Marca cotas sobre la imagen (escala de referencia) y define rangos (min/nom/max).

  4. Propuesta inicial — ≈1 min · Intervención: nula

    • Cálculos analíticos rápidos generan KPIs (ΔP, eficiencia, tamaño, potencia).

    • Reglas go/no‑go avisan si violas límites críticos.

    • Todo queda en Auditoría/Telemetry (JSONL firmado).

  5. Simulación automatizada — 5–30 min · Intervención: nula/monitor

    • Al pulsar Simular, corre un Pipeline (YAML): malla → OpenFOAM → posproceso → informe.

    • Se generan artefactos: mallas, CSV, imágenes, informe .rst→PDF.

  6. Revisión y decisión — 3–8 min · Intervención: alta

    • Tablero con tablas/gráficos, explicación de trade‑offs y supuestos.

    • Ajustas prioridades/entradas, recalculas, y apruebas o pides cambios.

  7. Informe y paquete comercial — ≈1 min · Intervención: nula

    • Genera el Informe reproducible .rst→PDF con figuras y anexos.

    • Crea paquete comercial (ZIP con PDF + PNG + CSV) para Aleph o envío.

  8. Reutilización y catálogo — ≈1 min · Intervención: baja

    • Guarda como Plantilla; inicia futuros casos desde allí.

  9. Búsqueda técnica — 2–5 min · Intervención: baja

    • Consulta en knowledge/ y obtén resúmenes y referencias (todo local).

  10. Seguridad y privacidad — ≈1 min · Intervención: nula

  • Circuito cerrado (sin conexiones externas), RBAC y checklist previo a entrega.

Mini‑glosario práctico

  • Caso: carpeta viva del proyecto con todo lo asociado.

  • YAML: archivo legible de configuración (clave: valor) para pipelines y metadatos.

  • Pipeline: receta automatizada (parámetros → malla → simulación → informe).

  • Artefacto: archivo generado (CSV, PDF, imagen, malla).

  • KPIs: métricas clave (ΔP, eficiencia…).

  • Auditoría/Telemetry: bitácora firmada (JSONL) de entradas/salidas/versión.

  • Perfil de decisión: prioridades ponderadas del ingeniero.

  • Go/No‑Go: reglas que aprueban o frenan un diseño por límites críticos.

  • Catálogo/Plantilla: biblioteca de casos exitosos reutilizables.

Diagramas de flujo (auto-generados)

.. figure:: flujo_interaccion_gemelo.png :align: center :width: 80%

.. figure:: flujo_pipeline.png :align: center :width: 80%

Anexos

  • Glosario de KPIs.

  • Checklist de validación.

  • Convenciones de nombres y rutas.