# 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.

## 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.
