# AGENTS.md Este archivo define el contexto operativo para agentes inteligentes y colaboradores que trabajen en EpicrisisIA. Sus instrucciones aplican a todo el repositorio, salvo que exista un `AGENTS.md` más específico en un subdirectorio. ## Contexto del Proyecto EpicrisisIA es una aplicación web orientada a la auditoría de casos médicos en el contexto colombiano. Su objetivo es procesar documentos clínicos, extraer y estructurar información relevante, apoyar la codificación CIE-10 y CUPS, validar información contra criterios SOAT, consolidar casos por paciente y generar epicrisis o reportes auditables. El sistema trabaja con documentos como historias clínicas, facturas, reportes quirúrgicos, radiología, laboratorio y documentos genéricos. El backend está construido con FastAPI, MongoDB, servicios de procesamiento clínico, modelos de lenguaje, componentes RAG/FAISS y procesamiento batch. El frontend usa HTML renderizado con Jinja2, recursos estáticos CSS/JavaScript y vistas orientadas a flujos operativos de auditoría. El desarrollo de agentes inteligentes busca: - Reducir trabajo manual repetitivo en revisión de documentos clínicos. - Detectar inconsistencias entre historia clínica, factura, ayudas diagnósticas, procedimientos y soportes. - Proponer codificación CIE-10, CUPS y validaciones SOAT trazables. - Apoyar la consolidación de casos médicos con evidencia documental. - Generar epicrisis, glosas, resúmenes y reportes auditables. - Mantener trazabilidad de decisiones automáticas y permitir validación humana. ## Relación con Historias de Usuario Cada cambio debe mapearse a una necesidad funcional o técnica expresada como historia de usuario, caso de uso o mejora de calidad. Antes de implementar, identifica qué flujo se impacta: - Carga individual de documentos clínicos. - Carga masiva por lotes y asociación de documentos a casos. - Extracción de texto y manejo de PDFs sin texto extraíble. - Clasificación del tipo documental. - Análisis clínico con LLM. - Codificación diagnóstica CIE-10. - Codificación de procedimientos CUPS. - Validación y consulta SOAT. - Consolidación de caso médico. - Generación, revisión y exportación de epicrisis. - Auditoría, trazabilidad y seguridad. Cuando una historia de usuario afecte varios módulos, conserva la separación por capas: el dominio expresa reglas, la aplicación coordina casos de uso, la infraestructura implementa adaptadores y las rutas exponen la interfaz HTTP. Las historias de usuario se encuentran disponibles en los archivos: `../../backlog/requirements/req/REQ-***.md`. Te debes basar en ellas para entender el contexto de cada cambio, identificar qué módulos se impactan y cómo validar que el cambio cumple con la necesidad expresada. ## Principios de Desarrollo Todo nuevo código debe ser coherente con el diseño existente y debe priorizar mantenibilidad, claridad y evolución incremental. - Aplica SOLID con criterio práctico. - Usa arquitectura hexagonal en backend. - Evita refactorizaciones prematuras o cosméticas. - Refactoriza código existente solo cuando sea necesario para implementar el cambio con calidad, reducir riesgo o eliminar duplicación real. - Mantén funciones, clases y módulos con una única responsabilidad. - Favorece composición, puertos e interfaces explícitas antes que acoplamientos directos. - Documenta decisiones complejas con comentarios breves y útiles. - No agregues comentarios que repitan literalmente lo que el código ya dice. - Preserva compatibilidad con flujos existentes salvo que la historia solicite romperla. - No mezcles reglas clínicas, presentación HTML, persistencia y llamadas a servicios externos en una misma unidad. - Agrega pruebas proporcionales al riesgo del cambio, especialmente en reglas de negocio, procesamiento clínico y flujos críticos de auditoría. - Al probar flujos con LLM, aísla la lógica de negocio de las llamadas al modelo para poder testear sin depender del proveedor. - Al probar flujos con LLM, no llames al modelo real en pruebas unitarias; usa mocks o fixtures con respuestas predefinidas para validar la lógica de negocio sin depender de la disponibilidad o costo del modelo. ## Arquitectura Backend El backend debe seguir arquitectura hexagonal con vertical slices para cada módulo funcional. La estructura objetivo es: - `domain/`: entidades, Value Objects, reglas de negocio, puertos y contratos del dominio. - `application/`: casos de uso, orquestación, servicios de aplicación y transformación entre comandos/consultas y dominio. - `infrastructure/`: repositorios MongoDB, clientes externos, extractores PDF, gateways LLM, exportadores Excel/PDF y otros adaptadores. - `routes/`: endpoints FastAPI, validación HTTP, autenticación y adaptación entre request/response y casos de uso. - `services/`: código legado o transversal debe migrarse gradualmente hacia módulos hexagonales cuando el cambio lo justifique. Reglas: - Las rutas no deben contener reglas de negocio complejas. - Los casos de uso no deben depender de MongoDB, FastAPI, HTML, Jinja2 ni clientes externos concretos. - La infraestructura puede depender de librerías externas, pero debe implementar puertos definidos por dominio/aplicación. - Los modelos de dominio no deben depender de detalles de persistencia. - Los adaptadores deben convertir documentos MongoDB u otras estructuras externas a modelos del dominio. ## Dominio con Pydantic El dominio debe construirse progresivamente con Pydantic para validar datos y expresar invariantes. - Usa modelos Pydantic para entidades y Value Objects del dominio. - Define Value Objects para conceptos con reglas propias: identificadores de caso, códigos CIE-10, códigos CUPS, tipos documentales, estados de auditoría, ayudas diagnósticas, resultados SOAT y evidencias. - Valida invariantes en el borde del dominio, no después de haber propagado datos inválidos. - Evita pasar diccionarios crudos entre capas cuando el dato ya tenga significado de dominio. - Usa serialización/deserialización de Pydantic para comunicación entre capas cuando aporte claridad. - Agrega pruebas unitarias para cada Value Object con reglas no triviales. - Mantén compatibilidad gradual con estructuras heredadas cuando el flujo ya dependa de diccionarios MongoDB. ## Frontend con Jinja2 Las plantillas están en `web/` y deben conservar separación de responsabilidades. - Usa Jinja2 para renderizar datos del servidor, no para implementar lógica compleja de negocio. - Prefiere macros, bloques e includes para construir componentes reutilizables. - Extrae patrones repetidos como botones, tarjetas, listas, alertas, tablas y formularios a macros o fragmentos cuando haya reutilización real. - Mantén las plantillas legibles: datos preparados por backend, presentación en Jinja2. - Evita duplicar estructuras HTML extensas en varias páginas. - Usa nombres de variables claros y alineados con el dominio. - No incrustes reglas clínicas complejas en la plantilla. Herramientas Jinja2 recomendadas: - `macros` para componentes pequeños reutilizables. - `include` para fragmentos de UI. - `extends` y `block` para layouts base y páginas especializadas. - filtros Jinja2 solo para formato/presentación, no para decisiones de negocio. ## JavaScript El JavaScript debe evolucionar hacia una estructura modular y mantenible. - Usa módulos ES2025 cuando sea viable para separar responsabilidades. - Divide código por comportamiento: estado de pantalla, persistencia de draft, validaciones, renderizado de listas, llamadas HTTP y utilidades. - Evita scripts monolíticos dentro de plantillas cuando el flujo crezca. - Mantén funciones pequeñas, nombradas y testeables. - No mezcles manipulación DOM, reglas clínicas y llamadas HTTP en la misma función si pueden separarse. - Usa `data-*` attributes para conectar HTML y comportamiento sin acoplarse a estilos CSS. - Implementa pruebas unitarias o de integración para lógica JavaScript cuando el flujo sea crítico. ## CSS El CSS debe organizarse para facilitar componentes reutilizables y separación de responsabilidades. La arquitectura objetivo (Atomic+ITCSS) es: ```text styles ├── settings │ ├── _colors.css │ ├── _typography.css │ └── _mixins.css │ ├── generic │ ├── _normalize.css │ └── _box-sizing.css │ ├── elements │ ├── _headings.css │ └── _links.css │ ├── atoms │ ├── _container.css │ ├── _button.css │ ├── _image.css │ ├── _pill.css │ └── _ui-list.css │ ├── molecules │ ├── _card.css │ └── _form.css │ ├── organisms │ ├── _gallery.css │ └── _header.css │ ├── utilities │ ├── _typography.css │ └── _error.css │ └── index.css ``` Reglas CSS: - Usa variables CSS para colores, espaciado, tipografía, radios, sombras y z-index. - Usa Grid o Flexbox para layout; evita posicionamiento absoluto salvo que esté justificado. - Mantén estilos de componentes encapsulados por responsabilidad. - Usa utilidades para ajustes pequeños y repetibles, no para reemplazar componentes completos. - Documenta con comentarios breves las decisiones de diseño no evidentes. - Evita estilos inline salvo en HTML generado excepcional o estados temporales heredados. - Mantén consistencia responsive en escritorio y móvil. - Agrega pruebas visuales para flujos críticos o interfaces con alto riesgo de regresión. ## Pruebas Toda funcionalidad relevante debe incluir pruebas proporcionales al riesgo. - Usa pruebas unitarias para Value Objects, utilidades puras y reglas de dominio. - Usa pruebas de casos de uso para orquestación de aplicación. - Usa pruebas de integración para repositorios, rutas y flujos con persistencia cuando sea necesario. - Usa pruebas visuales para cambios de UI significativos. - Cubre regresiones en procesamiento batch, epicrisis, SOAT, CIE-10, CUPS y auditoría cuando el cambio toque esos flujos. - No afirmes que una funcionalidad está validada si no ejecutaste o agregaste la prueba correspondiente. Comandos habituales: ```bash python -m pytest python -m pytest test/test_case_epicrisis.py python -m pytest test/test_batch_processing.py ruff check app modules test ruff format app modules test ``` ## Auditoría, Seguridad y Datos Clínicos Este sistema trata información clínica sensible. Todo agente debe aplicar mínimo privilegio y trazabilidad. - No registres texto clínico crudo innecesario en logs. - No registres prompts completos, respuestas completas de LLM, JWT, cookies o llaves de API. - Mantén la política de auditoría orientada a metadatos. - Toda decisión automática relevante debe guardar evidencia, fuente, score o razón de inclusión cuando aplique. - Los errores deben ser accionables y no exponer secretos. - Los documentos sin texto extraíble deben conservar trazabilidad y requerir revisión manual cuando corresponda. ## Relación entre Agentes Inteligentes y Auditoría Médica Los agentes inteligentes deben actuar como apoyo a la auditoría, no como reemplazo de la validación humana. - Extraen señales clínicas y administrativas. - Proponen asociaciones entre documentos y casos. - Detectan ayudas diagnósticas ordenadas, interpretadas, facturadas, glosadas o pendientes. - Recomiendan códigos y soportes documentales. - Explican razones de inclusión, exclusión o alerta. - Permiten que el auditor acepte, corrija o descarte resultados. Toda recomendación de agente debe ser trazable a documentos, reglas, evidencia o resultados de búsqueda. ## Control de Alcance y Preservación de Cambios El requerimiento acordado con el usuario define el límite estricto de cada intervención. Implementa únicamente el comportamiento solicitado y conserva el comportamiento existente que no forme parte explícita del objetivo. - No realices refactorización, limpiezas, renombres, sustituciones, cambios cosméticos ni otras modificaciones no solicitadas. - No elimines, sobrescribas ni deshabilites código, pruebas, funcionalidades, rutas, estilos o configuraciones existentes y aprobadas sin autorización explícita del usuario. - Antes de editar, inspecciona los archivos afectados y los cambios locales existentes. Preserva todo cambio ajeno al objetivo, incluso si parece incompleto o mejorable. - Solo se permiten cambios auxiliares mínimos y directamente necesarios para cumplir el objetivo, incluidas pruebas de regresión. Justifica concretamente cada uno en el reporte final. - Si el alcance es ambiguo, existe riesgo de regresión o es necesario tocar un módulo no mencionado, detén la implementación y formula las preguntas necesarias en Plan Mode antes de editar. - Antes de finalizar, revisa el diff contra el alcance acordado, confirma que no existan cambios no solicitados y ejecuta únicamente las pruebas pertinentes. ## Criterios de Calidad para Nuevos Cambios Antes de finalizar un cambio: - Verifica que el cambio corresponda a una historia, caso de uso u objetivo técnico claro. - Confirma que la responsabilidad esté en la capa correcta. - Evita introducir dependencias desde dominio hacia infraestructura. - Agrega o ajusta pruebas relevantes. - Actualiza documentación cuando cambie un flujo, contrato o decisión arquitectónica. - Revisa compatibilidad con datos existentes en MongoDB. - Mantén nombres consistentes con el lenguaje del dominio clínico y de auditoría. - Prefiere cambios pequeños, comprensibles y revisables. ## Guía de Refactorización Refactoriza cuando: - El cambio exige tocar una zona con duplicación riesgosa. - Una regla de negocio está mezclada con rutas, plantillas o persistencia. - El código impide pruebas razonables. - Un modelo de dominio necesita invariantes explícitas. - Un adaptador concreto está acoplado a un caso de uso. - Un controlador está acoplado a multiples responsabilidades dentro de una ruta. Evita refactorizar cuando: - La mejora es puramente estética y no reduce riesgo. - El cambio aumenta alcance sin relación con la historia. - No hay pruebas suficientes para proteger el comportamiento. ## Convenciones de Implementación - Python objetivo: 3.12. - Estilo: `ruff.toml`, línea de 110 caracteres. - Entry point vigente: `uvicorn app.main:app --host 0.0.0.0 --port 7000 --reload`. - El repositorio expone comandos operativos mediante `Makefile` para estandarizar el trabajo local. - El `Makefile` debe mantenerse portable para Linux/macOS y Windows nativo cuando sea viable. - `uv` se usa como flujo recomendado de desarrollo local y debe operar desde `pyproject.toml` y `uv.lock`. - `requirements.txt` y `requirements-dev.txt` deben mantenerse como exports compatibles para entornos que usan `pip`. - `pip` sigue siendo el camino compatible con producción y no debe eliminarse ni asumirse obsoleto. - Mantén nombres de archivos y módulos descriptivos. - Usa tipos explícitos en funciones públicas. - Prefiere inyección de dependencias para servicios externos. - No introduzcas nuevas librerías sin justificación clara. - Aísla llamadas LLM para poder testear flujos sin depender del proveedor. ### Comandos Operativos Locales Para evitar variaciones entre colaboradores y agentes, usa preferentemente estos comandos del `Makefile` cuando apliquen: ```bash make help make uv-sync make install make run make worker make test make lint make format make migrate make bootstrap-admin make warmup ``` Convenciones de uso: - `make uv-sync`: crea `.venv` con `uv` y sincroniza dependencias desde `pyproject.toml` y `uv.lock`. Es el flujo recomendado para desarrollo local. - `make deps-export`: regenera `uv.lock`, `requirements.txt` y `requirements-dev.txt` desde `pyproject.toml`. - `make install`: crea `.venv` con `python -m venv` e instala dependencias con `pip`. Es el flujo compatible con entornos que no usan `uv`. - `make run`: arranca FastAPI en local con reload. - `make worker`: arranca el worker Celery del proyecto. - `make test`: ejecuta la suite de pruebas con el Python del entorno local. - `make lint`: ejecuta `ruff check app modules test`. - `make format`: ejecuta `ruff format app modules test`. - `make migrate`: aplica migraciones MongoDB del proyecto. - `make bootstrap-admin`: ejecuta el bootstrap explícito del usuario administrador. - `make warmup`: precarga recursos pesados de CIE-10 y CUPS. Regla para agentes: - Si existe un target `make` adecuado para la tarea local solicitada, prefierelo sobre invocar manualmente el comando subyacente, salvo que haya una razón técnica concreta para no hacerlo.