Gemelo Operativo Prodisys¶

Diseño técnico consolidado, evolución estratégica y hoja de ruta¶

Estado:: Documento consolidado para publicación
Base documental:: tres documentos de evolución del Gemelo Operativo Prodisys
Criterio de consolidación:: prevalece la definición más reciente; los documentos anteriores se conservan como contexto cuando no contradicen la evolución posterior.

1. Propósito y criterio de consolidación¶

Este documento consolida la evolución conceptual y técnica del Gemelo Operativo Prodisys a partir de tres documentos desarrollados en momentos sucesivos.

La precedencia utilizada es:

Fase 2 – Gemelo Operativo Prodisys: fuente principal para arquitectura, objetivos, métricas, seguridad, experiencia de uso y hoja de ruta.
Gemelo Operativo Prodisys — Diseño Técnico Unificado + Bitácora Estratégica (Fase 1–2.5): fuente para la visión integral, el modelo basado en proyectos, la ingesta, la memoria y la integración con Aleph.
Avatar Operativo — Conversación Técnica y Plan Integrado: antecedente conceptual para el componente cognitivo, el agente ejecutor, las skills, las políticas y el ciclo de control.

La consolidación distingue deliberadamente entre:

principios y decisiones arquitectónicas;
arquitectura objetivo o propuesta;
capacidades y flujos previstos;
hoja de ruta y métricas objetivo.

Los documentos fuente no permiten certificar por sí solos que todas las capacidades descritas estén implementadas actualmente. Por ello, una propuesta, un objetivo o un diseño futuro no se presenta aquí como funcionalidad ya desplegada.

2. Resumen ejecutivo¶

El Gemelo Operativo Prodisys se concibe como una plataforma para apoyar el diseño y desarrollo de equipos y conectar progresivamente los procesos reales de ingeniería, simulación, documentación, aprendizaje técnico y gestión empresarial.

Las familias de equipos identificadas inicialmente incluyen hidrociclones y aeroenfriadores; los documentos de evolución también contemplan eductores y otras familias desarrolladas por Prodisys.

La dirección técnica más reciente prioriza:

desacoplar la lógica de cálculo de cualquier interfaz específica;
consolidar un núcleo de dominio reutilizable;
automatizar el flujo diseño–simulación–posproceso–informe;
utilizar una arquitectura hexagonal basada en Ports & Adapters;
formalizar contratos de datos;
mantener trazabilidad de parámetros, código, modelos y artefactos;
construir un catálogo reutilizable de diseños;
habilitar búsqueda técnica local;
integrar progresivamente Aleph;
preservar privacidad, control humano y operación en infraestructura controlada.

El concepto original de avatar evoluciona así hacia un sistema operativo técnico más amplio. El objetivo principal deja de ser representar visualmente a una persona y pasa a ser reproducir de manera verificable sus procesos, criterios, conocimiento y formas de decisión.

3. Evolución conceptual¶

3.1. Antecedente: avatar operativo¶

El planteamiento inicial separaba el avatar en tres capas:

Capa cognitiva: Representación de criterios, prioridades, patrones de decisión y estilo de razonamiento.
Capa funcional: Capacidad de ejecutar notebooks, scripts, cálculos, consultas SQL, manejo de archivos y otras acciones técnicas.
Capa interactiva: Comunicación con el usuario mediante texto y, opcionalmente, mecanismos visuales o de voz.

La evolución posterior conserva las dos primeras como componentes relevantes, pero reduce la prioridad de una representación visual. El foco pasa a ser el Gemelo Operativo como extensión técnica y operativa.

3.2. De aplicación de cálculo a sistema transversal¶

La visión evoluciona desde una aplicación Jupyter centrada en cálculo hacia un sistema que debe poder relacionar:

planeación y contexto de proyecto;
diseño de equipos;
hidráulica;
CFD;
bosquejos y notas;
informes;
ofertas;
información empresarial;
decisiones;
resultados;
lecciones aprendidas.

La interfaz Jupyter se conserva para cálculos detallados y flujos interactivos, pero deja de ser el centro arquitectónico.

3.3. Proyecto o caso como unidad natural¶

Los documentos posteriores establecen que el sistema debe organizarse alrededor de proyectos o casos, no de herramientas aisladas.

Un caso representa un expediente vivo que puede agrupar:

objetivo;
familia de equipo;
bosquejo;
parámetros;
supuestos;
criterios de éxito;
simulaciones;
KPIs;
decisiones;
informes;
artefactos;
contexto comercial;
lecciones aprendidas.

4. Objetivos de la Fase 2¶

La definición más reciente establece los siguientes objetivos de referencia para un horizonte inicial de 90 días:

Desacople arquitectónico: extraer el dominio de cálculo en librerías y servicios reutilizables.
Pipeline diseño–simulación–informe: parámetros → malla → OpenFOAM → posproceso → informe reproducible.
Catálogo de diseños: plantillas parametrizadas, versionadas y comparables.
Trazabilidad y auditoría: vincular cada resultado con insumos, commit, configuración y versión de modelo.
Búsqueda técnica: extraer fórmulas, rangos y criterios desde literatura técnica.
Entrega comercial: generar paquetes de KPIs, gráficas CFD e informes para integración comercial y Aleph.

4.1. Alcance¶

Familias iniciales

Hidrociclón.
Aeroenfriador.

La documentación estratégica adicional contempla eductores y otras familias en fases posteriores.

Integraciones previstas

OpenFOAM.
Git.
Aleph.

Fuera del alcance inicial

control de planta;
IoT.

Estos elementos se consideran una evolución futura.

5. Arquitectura propuesta¶

5.1. Arquitectura hexagonal¶

La definición más reciente adopta una arquitectura hexagonal.

Dominio: Fórmulas, validaciones y criterios de ingeniería sin dependencias de UI.
Aplicación / Servicios: Orquestación de casos, pipelines, simulaciones e informes.
Adaptadores: UI, CLI, API, OpenFOAM, Aleph y otros sistemas externos.
Infraestructura: Telemetría, almacenamiento, caché, seguridad y servicios de soporte.

Patrones principales:

Ports & Adapters;
pipelines declarativos;
contratos de datos;
separación entre dominio e infraestructura.

Los contratos de datos se proponen mediante herramientas como Pydantic.

6. Arquitectura objetivo del repositorio¶

La estructura de referencia más reciente es:

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

Los documentos estratégicos amplían esta dirección con capacidades de ingesta, memoria y seguridad:

prodisys/
  ingest/
  memory/
  security/

knowledge/
templates/
catalogo/
cases/
artifacts/
docs/

Esta estructura representa una arquitectura objetivo. No implica que todos los módulos estén implementados ni que las rutas históricas deban migrarse de forma inmediata.

7. Núcleo de dominio y cálculo¶

7.1. `prodisys/core`¶

Debe contener la lógica estable e independiente de interfaces.

Áreas conceptuales:

physics/
design/
standards/
utils/

Responsabilidades:

criterios físicos;
hidráulica;
termodinámica;
validaciones;
unidades;
algoritmos de dimensionamiento;
reglas de diseño;
criterios ASME/API/ISO cuando correspondan.

7.2. `prodisys/calc`¶

Agrupa capacidades de cálculo y soporte a simulación:

cálculos hidráulicos;
esfuerzos;
flujo multifásico;
evaluación de KPIs;
integración con simulaciones;
modelos predictivos cuando exista evidencia suficiente.

7.3. `prodisys/equipos`¶

Organiza conocimiento y lógica por familia de equipo, comenzando por:

hidrociclones;
aeroenfriadores.

La documentación estratégica contempla posteriormente:

eductores;
sellos hidrodinámicos;
otras familias desarrolladas por Prodisys.

8. Pipeline de diseño, simulación e informe¶

El pipeline objetivo es:

parámetros
    ↓
geometría / preparación de caso
    ↓
malla
    ↓
OpenFOAM
    ↓
posproceso
    ↓
KPIs
    ↓
comparación
    ↓
informe .rst / PDF
    ↓
paquete de evidencia

Los pipelines deben ser declarativos cuando resulte práctico, por ejemplo mediante YAML.

Cada ejecución debe conservar información suficiente para reproducir el resultado.

9. Mapa de capacidades¶

Capacidad	Entrada	Salida
Cálculo rápido	YAML/JSON	KPIs preliminares
Simulación CFD/CAE	Caso OpenFOAM + geometría	Campos, KPIs e imágenes
Comparación multi-escenario	Resultados de escenarios	Tablas y gráficos
Generación de evidencia	Parámetros + resultados	Informe `.rst` / PDF
Catálogo y reutilización	Metadatos	Plantillas parametrizadas
Búsqueda técnica	Consulta	Criterios y referencias

10. Ingesta de conocimiento¶

El segundo documento identifica la ingesta como una pieza estructural del Gemelo Operativo.

Fuentes previstas:

informes PDF, Markdown y RST;
resultados CFD;
casos OpenFOAM;
geometrías;
notas;
fotografías;
bosquejos;
cálculos preliminares;
ofertas;
información de proyectos;
hojas de cálculo;
documentos históricos.

Módulos conceptuales:

prodisys/ingest/
  ingest_report.py
  ingest_cfd.py
  ingest_manual.py
  ingest_project.py
  ingest_offers.py
  parsers/

El objetivo es convertir información dispersa en datos y conocimiento recuperables sin perder el vínculo con la fuente original.

11. Búsqueda técnica¶

La Fase 2 propone una base local de conocimiento:

knowledge/
  PDFs
  metadatos YAML
  referencias
  criterios extraídos

La búsqueda técnica debe permitir recuperar:

fórmulas;
rangos;
criterios de diseño;
referencias;
restricciones;
antecedentes comparables.

La trazabilidad de la fuente es necesaria para que el criterio recuperado pueda ser verificado.

12. Memoria del gemelo¶

12.1. Memoria técnica o semántica¶

El documento estratégico propone un almacenamiento local de representaciones semánticas de:

informes;
correos técnicos;
notas;
explicaciones;
documentación de proyectos.

Su propósito es recuperar contexto y conocimiento relevante.

12.2. Memoria episódica¶

Debe registrar:

decisiones;
resultados de simulaciones;
parámetros recurrentes;
correcciones;
criterios aplicados;
lecciones aprendidas.

El registro de memoria debe preservar contexto y procedencia.

13. Componente cognitivo y perfil de decisión¶

La Fase 2 conserva y formaliza el concepto cognitivo inicial.

13.1. Bosquejos¶

Flujo propuesto:

fotografía
    ↓
inbox_sketches/
    ↓
contexto + objetivos + supuestos
    ↓
ficha de diseño
    ↓
caso / catálogo

13.2. Extracción¶

Se contemplan:

marcado de cotas;
escala de referencia;
valores con incertidumbre;
rangos mínimo / nominal / máximo;
heurísticas por familia.

13.3. Perfil de decisión¶

El perfil puede representar prioridades como:

seguridad;
eficiencia;
costo;
mantenibilidad;
plazo.

Debe mantenerse explícito y auditable.

13.4. Reglas Go/No-Go¶

Las reglas permiten detener o advertir sobre alternativas que violen límites críticos.

13.5. Feedback y heurísticas¶

El documento más reciente contempla:

feedback explícito mediante aprobaciones y prioridades;
feedback implícito mediante uso y selecciones;
ajuste de pesos;
ranking;
evolución de reglas;
trazabilidad de decisiones.

También menciona técnicas como multi-armed bandit como posibilidad de evolución, no como requisito inicial.

14. Agente ejecutor¶

El documento inicial propuso una arquitectura de agente con componentes de orquestación, razonamiento, planificación, políticas y skills.

Estructura conceptual histórica:

src/
  agent/
    orchestrator.py
    reasoning.py
    planner.py
    policy.py
  skills/
    python_exec.py
    sql_exec.py
    files.py
    reports.py
    git_ops.py
  memory/
    episodic_store.py
    retriever.py
  security/
    sandbox.py
  telemetry/
    logger.py
    audit.py

Esta estructura se conserva como referencia funcional, no como obligación sobre la arquitectura canónica más reciente bajo prodisys/.

15. Ciclo de control del agente¶

Pseudocódigo original:

while objetivos_pendientes:
    objetivo = planner.descomponer_objetivo()
    subtareas = reasoning.validar(objetivo)

    for tarea in subtareas:
        if policy.is_allowed(tarea):
            resultado = skill.ejecutar(tarea)
            episodic_store.registrar(resultado)
            logger.log_event("task_done", tarea)
        else:
            logger.log_event("blocked_by_policy", tarea)

El principio que permanece vigente es que toda ejecución debe pasar por una política explícita antes de modificar recursos.

16. Ejemplos históricos de operación segura¶

Los siguientes ejemplos pertenecen al diseño inicial y se conservan como referencia de la filosofía de ejecución controlada.

16.1. Prueba del agente en modo lectura¶

from src.agent.orchestrator import Agent
from src.memory.episodic_store import EpisodicStore
from src.telemetry.logger import log_event

plan = [
    {
        "action": "read_sql",
        "params": {
            "query": "SELECT TOP 5 * FROM ISOMETRICOS"
        },
    },
]

log_event("agent_smoke_start", {"note": "solo-lectura"})
Agent(EpisodicStore()).run("Prueba agente sin tocar nada", plan)
log_event("agent_smoke_end", {"ok": True})

16.2. Política de bloqueo de escritura¶

plan = [
    {
        "action": "read_sql",
        "params": {
            "query": "SELECT TOP 3 * FROM ISOMETRICOS"
        },
    },
    {
        "action": "export_report",
        "params": {
            "path": "/mnt/data/reporte_prueba.csv"
        },
    },
]

Agent(EpisodicStore()).run("Check bloqueo escritura", plan)

16.3. Consulta segura del esquema SQL Server¶

from src.skills.sql_exec import read_sql

schema_cols = read_sql(
    '''
    SELECT COLUMN_NAME, DATA_TYPE
    FROM INFORMATION_SCHEMA.COLUMNS
    WHERE TABLE_NAME = 'ISOMETRICOS'
    ORDER BY ORDINAL_POSITION
    '''
)

for row in schema_cols:
    print(row["COLUMN_NAME"], row["DATA_TYPE"])

17. Integración con Aleph¶

La evolución estratégica asigna a Aleph un papel importante como fuente de contexto empresarial e histórico.

Información prevista:

empresas;
personas;
visitas y comunicaciones;
proyectos;
cotizaciones;
contratos;
materiales;
mano de obra;
equipos;
transporte;
subcontratos;
APUs;
seguimiento.

Esta información puede alimentar análisis futuros sobre:

costos reales;
tiempos reales;
éxito comercial;
comportamiento de ofertas;
riesgos contractuales;
patrones de compra;
relación entre aplicación, diseño y resultado.

La arquitectura más reciente exige que esta integración se realice mediante adaptadores, preservando el desacople del dominio.

18. Aprendizaje híbrido¶

18.1. Datos estructurados¶

Fuentes propuestas:

CFD;
hidráulica;
APUs;
cotizaciones;
contratos;
parámetros de diseño.

Variables o resultados potencialmente modelables:

caída de presión;
eficiencia;
erosión;
peso;
costo;
probabilidad de cierre;
tiempo de ejecución.

18.2. Datos no estructurados¶

Fuentes:

informes;
conclusiones;
notas;
correos técnicos;
bitácoras.

Usos:

explicación;
recomendación;
comparación;
recuperación de antecedentes;
búsqueda técnica.

La existencia de estas fuentes no implica que los correspondientes modelos estén ya entrenados o desplegados.

19. Trazabilidad y auditoría¶

Cada resultado debería relacionarse con:

insumos;
parámetros;
commit;
configuración;
versión de modelo;
artefactos;
decisiones;
validaciones.

La Fase 2 propone auditoría basada en JSONL y, para artefactos relevantes, hashes o checksums.

Ejemplo de ubicación propuesta:

logs/agent.log.jsonl

La trazabilidad debe permitir responder qué se ejecutó, con qué información y qué produjo.

20. Seguridad y privacidad¶

20.1. Sistema cerrado por defecto¶

La definición más reciente establece:

no enviar documentos ni parámetros a terceros por defecto;
utilizar modelos locales o infraestructura controlada;
impedir telemetría saliente no autorizada.

20.2. Control de acceso¶

Se propone RBAC con roles como:

Administrador;
Ingeniería;
Comercial.

20.3. Secretos¶

Las claves no deben permanecer en texto plano en el repositorio. La arquitectura propone un gestor como Vault.

20.4. Red¶

Se propone una política deny-all egress para contenedores, autorizando únicamente los repositorios y nodos requeridos.

20.5. Clasificación de información¶

Clases propuestas:

INTERNAL;
CONFIDENTIAL;
CLIENT_CONFIDENTIAL.

20.6. Backups y retención¶

La política propuesta incluye:

snapshots cifrados;
retención diferenciada;
eliminación controlada cuando corresponda.

El documento fuente propone como referencia:

90 días para datos temporales;
1 año para resultados;
conservación indefinida de informes finales archivados.

Estos plazos deben considerarse política propuesta hasta su aprobación formal.

20.7. Controles¶

prueba de circuito cerrado;
escaneo de secretos en CI;
bloqueo de credenciales;
revisión periódica de permisos;
auditoría de artefactos;
checklist de privacidad.

21. Checklist de privacidad previo a entrega¶

Verificar clasificación de cada artefacto.
Confirmar ausencia de llamadas externas no autorizadas.
Revisar hashes o firmas de auditoría cuando correspondan.
Verificar que no existan claves expuestas.
Comprobar cifrado y permisos de backups.
Revisar nombres de archivo para evitar exposición innecesaria de información.
Registrar aprobación final cuando la política aplicable lo requiera.

22. Experiencia de uso prevista¶

La Fase 2 describe un flujo de interacción de referencia.

22.1. Crear un caso¶

Tiempo orientativo del documento fuente: 1–2 minutos.

Acciones:

elegir rol;
crear caso;
definir objetivo;
seleccionar familia;
cargar bosquejo.

22.2. Ficha de diseño¶

Tiempo orientativo: 3–6 minutos.

El usuario completa:

contexto;
supuestos;
criterios de éxito;
prioridades.

Los metadatos pueden conservarse en YAML.

22.3. Preguntas inteligentes¶

Tiempo orientativo: 2–4 minutos.

El gemelo plantea preguntas breves para aclarar:

dimensiones;
límites;
incertidumbre;
rangos.

22.4. Propuesta inicial¶

Se generan cálculos analíticos rápidos y KPIs preliminares.

Las reglas go/no-go detectan violaciones de límites críticos.

22.5. Simulación¶

Tiempo orientativo del documento fuente: 5–30 minutos, sujeto a complejidad y recursos.

Flujo:

malla → OpenFOAM → posproceso → informe

Artefactos posibles:

mallas;
CSV;
imágenes;
resultados;
informe.

22.6. Revisión y decisión¶

El usuario revisa:

KPIs;
gráficos;
trade-offs;
supuestos.

Después puede aprobar, modificar o solicitar una nueva iteración.

22.7. Informe y paquete comercial¶

Se propone generar:

PDF;
PNG;
CSV;
paquete comercial para Aleph o entrega.

22.8. Reutilización¶

Un caso validado puede guardarse como plantilla.

22.9. Búsqueda técnica¶

El usuario consulta knowledge/ para recuperar referencias y criterios.

22.10. Seguridad¶

La operación se realiza bajo políticas de circuito cerrado, permisos y auditoría.

23. Métricas objetivo¶

La Fase 2 propone como indicadores iniciales:

T2E inferior a 48 horas hasta informe PDF;
al menos 50 % de casos nuevos iniciados desde una plantilla;
al menos 80 % de pasos automatizados;
checklist de calidad por caso.

Estas cifras se conservan como metas de la Fase 2, no como desempeño demostrado.

24. Roadmap consolidado¶

24.1. Horizonte inicial¶

Mes 1

desacoplar núcleo de dominio;
consolidar prodisys.core, prodisys.calc y prodisys.equipos;
CLI mínima;
flujo de bosquejos con YAML.

Mes 2

pipeline OpenFOAM;
casekit;
informes .rst automáticos;
catálogo;
comparación de resultados.

Mes 3

UI como adaptador;
exportación comercial;
auditoría;
diálogo de verificación.

La tabla de hitos de la fuente también contempla un cuarto bloque orientado a validación, trazabilidad y privacidad.

24.2. Evolución estratégica posterior¶

Los documentos estratégicos añaden:

ingesta completa;
dataset histórico + nuevo;
memoria técnica;
integración progresiva con Aleph;
aprendizaje continuo;
expansión multiequipos;
análisis de riesgos;
simulaciones predictivas;
asistencia técnica.

25. Siguientes pasos¶

La lista original de la Fase 2 incluía:

crear el repositorio prodisys-gemelo;
extraer prodisys-core;
especificar el pipeline YAML de hidrociclón;
implementar CLI y prueba end-to-end;
definir plantilla .rst y salida PDF;
activar inbox_sketches/.

Como el documento consolidado no certifica el estado actual del repositorio, estos elementos deben verificarse antes de tratarlos como pendientes vigentes.

La secuencia arquitectónica recomendada por las tres fuentes es:

núcleo desacoplado
    ↓
pipelines reproducibles
    ↓
trazabilidad
    ↓
ingesta
    ↓
búsqueda y memoria
    ↓
integración empresarial
    ↓
asistencia cognitiva
    ↓
autonomía supervisada

26. Riesgos y mitigaciones¶

Acoplamiento residual: Mitigación: tests de contrato, puertos y adaptadores.
Variabilidad del solver: Mitigación: recetas versionadas, settings y tolerancias.
Gestión de artefactos: Mitigación: convenciones, catálogo, retención y limpieza controlada.
Automatización no supervisada: Mitigación: sandbox, políticas, dry-run y aprobación humana.
Datos históricos heterogéneos: Mitigación: contratos de datos, validación y procedencia.
Adopción prematura de modelos cognitivos: Mitigación: estabilizar primero datos, pipelines y trazabilidad.

27. Glosario operativo¶

Adaptador: Componente que conecta el dominio con una interfaz o sistema externo.
Artefacto: Archivo o resultado generado: código, CSV, PNG, PDF, malla o caso de simulación.
Auditoría / Telemetry: Registro cronológico de qué se ejecutó, con qué entradas y qué produjo.
Caso: Expediente vivo de diseño que agrupa contexto, entradas, resultados y decisiones.
CLI: Interfaz de línea de comandos.
Data Contract: Definición explícita de la estructura y validación de los datos intercambiados entre componentes.
Dominio: Ingeniería pura: fórmulas, criterios y validaciones independientes de la UI.
Go/No-Go: Regla que permite, advierte o detiene una alternativa frente a un límite crítico.
KPIs: Indicadores cuantitativos de desempeño.
Pipeline: Receta automatizada que transforma entradas en artefactos y resultados.
Perfil de decisión: Conjunto explícito de prioridades y criterios utilizados para comparar alternativas.
YAML: Formato de texto legible utilizado para configuraciones y metadatos.

28. Diagramas previstos¶

Los siguientes diagramas están previstos y pendientes de incorporación:

Flujo de interacción previsto para el Gemelo Operativo.
Pipeline de diseño, simulación, posproceso e informe.

29. Conclusión¶

El Gemelo Operativo Prodisys evoluciona desde la idea inicial de un avatar ejecutor hacia una arquitectura técnica centrada en dominio, proyectos, reproducibilidad, conocimiento y control.

La definición más reciente aporta la estructura arquitectónica más concreta: Ports & Adapters, pipelines declarativos, contratos de datos, catálogo, trazabilidad, búsqueda técnica, privacidad y una experiencia de usuario basada en casos.

La visión estratégica complementaria amplía ese núcleo con ingesta de información histórica, memoria, integración con Aleph y aprendizaje híbrido.

El componente cognitivo debe construirse sobre esa base y no sustituirla. La autonomía debe incorporarse progresivamente, con políticas explícitas y trazabilidad.

El objetivo final es que el gemelo pueda apoyar el ciclo completo:

contexto
   ↓
diseño
   ↓
cálculo
   ↓
simulación
   ↓
evidencia
   ↓
decisión
   ↓
entrega
   ↓
aprendizaje

manteniendo siempre reproducibilidad, privacidad y control humano.