README.md

---
title: Morphos
emoji: 🐕
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---
# Morphos — Intérprete de analíticas veterinarias asistido por I.A

## Proyecto final — Curso de Desarrollo Web 2026

> El proyecto se entregó sobre un stack XAMPP (PHP + JS sin build) y desde entonces se
> migró a **Vite + TypeScript (`frontend/`) + FastAPI (`backend/`)**; `js/*.js`, `api/*.php`
> y `.htaccess` se eliminaron el 2026-07-26. Este README describe el estado **actual**. El
> detalle de la migración está en `MIGRACION.md` y la arquitectura viva en `CLAUDE.md`.

---

## Descripción

Morphos es una aplicación web de apoyo al diagnóstico veterinario. Detecta patrones clínicos en tiempo real a partir de valores de laboratorio con un motor propio que corre entero en el navegador, y permite interpretarlos con un modelo de IA especializado en medicina (medGemma multimodal de Google DeepMind, auto-alojado) o con Claude. Incluye búsqueda de artículos científicos en PubMed relacionados con los diagnósticos diferenciales del paciente.

Está orientada a caninos y felinos, con ajuste automático de rangos de referencia por especie, edad, raza y sexo.
Ataca una necesidad real del sector veterinario que actualmente no dispone de herramientas de este tipo que sean gratuitas y de fácil uso y que permitan obtener información complementaria relevante sobre sus pacientes en muy poco tiempo y sin exponer la data sensible a los LLM.

Funcionalidades principales:

```text
Detección de patrones clínicos en tiempo real (motor determinista en el cliente)
Interpretación con IA: medGemma auto-alojado (HF Space u Ollama) o Claude
Respuesta clínica estructurada y validada, con citas a literatura veterinaria (RAG)
Importación de resultados desde PDF, sin subir el archivo a ningún servidor
Análisis de citologías mediante imágenes
Ingesta directa de resultados desde analizadores de laboratorio (ASTM/HL7)
Búsqueda de literatura científica en PubMed
Sistema de autenticación con registro e inicio de sesión
```

---

## Objetivo del proyecto

Integrar los conocimientos del curso en una aplicación web completa que además sea útil y
cubra una necesidad de mercado. El entregable del curso cubría HTML semántico, CSS
propio sin frameworks, JavaScript modular y PHP como backend; la evolución posterior
mantiene esos principios y sustituye la implementación:

```text
HTML semántico y accesible                → intacto
CSS personalizado (variables, grid)       → intacto, sin framework
JavaScript modular                        → TypeScript con build (Vite) y tipos estrictos
PHP como backend de API                   → FastAPI (Python 3.12, gestionado con uv)
```

Conceptos aplicados:

* Separación de responsabilidades por módulos
* Comunicación asíncrona con `fetch` (JSON y SSE)
* Sesiones firmadas y autenticación con contraseñas hasheadas (scrypt)
* Consultas parametrizadas para prevenir inyección SQL
* Detección de patrones mediante lógica clínica codificada
* Salida del modelo **estructurada y validada** (Pydantic) en lugar de texto libre
* Suite de regresión del motor y evals clínicas como puerta de CI

---

## Estructura del proyecto

```text
/frontend
    src/analisis.ts  → motor de detección de patrones clínicos (única fuente de verdad)
    src/main.ts      → orquestación general, eventos y renderizado
    src/ia.ts        → cliente tipado de /api/interpret y render de la salida estructurada
    src/ui.ts        → navegación por tabs, gestos, sincronización móvil
    src/auth.ts      → modal de autenticación y validación en tiempo real
    src/papers.ts    → búsqueda y paginación de literatura científica
    src/pdf-parser.ts→ extracción de valores desde PDF en el navegador
    tests/           → suite de regresión del motor (Vitest)

/backend
    app/main.py      → app FastAPI, CORS, cabeceras, montaje de estáticos
    app/config.py    → configuración por variables de entorno (sin secretos por defecto)
    app/schemas.py   → esquemas Pydantic: petición y salida clínica validada
    app/ai/          → rutas de modelo (hf_space, medgemma/Ollama, claude), prompt y citas
    app/rag/         → ingesta e índice LanceDB + recuperación híbrida con reranking
    app/routers/     → interpret, auth, papers, lab
    app/security/    → sesión firmada, CSRF, rate limiting, cabeceras, auth de dispositivos
    tests/           → pruebas de esquema, prompt, RAG, citas, API y seguridad

/evals
    dataset/         → casos dorados (split dev/test + firma veterinaria)
    run_evals.py     → puerta de CI: métricas deterministas + juez clínico
    judge/           → juez LLM local y gratuito (Ollama) o Claude
    run_ragas.py     → groundedness del RAG (faithfulness, precisión/recall de contexto)

/bridge              → puente local que lee analizadores (ASTM/HL7) en la LAN de la clínica

/css
    styles.css       → estilos completos (tema claro/oscuro, grid, mobile)

/data
    valores_referencia.json → rangos de referencia por especie y analito
    alteraciones.json       → descripciones clínicas de los patrones

/assets
    /fonts           → Inter y JetBrains Mono (carga local)
    /icons           → iconos SVG de la interfaz
    /lib/pdfjs       → librería PDF.js en local

/instance            → BD de usuarios e índice RAG, FUERA de la raíz servida (gitignored)
index.html           → SPA principal (carga el bundle de frontend/)
Dockerfile           → imagen de despliegue (frontend + backend + índice RAG horneado)
```

---

## Flujo de la aplicación

```text
[ Formulario de valores ]
        |
        v
   analisis.ts
   (deteccion de patrones en tiempo real, sin servidor)
        |
        v
[ UI: campos coloreados + tarjetas de patron ]
        |
        v
  Usuario pulsa "Analisis IA"
        |
        v
   ia.ts  → POST /api/interpret  (sesion + CSRF + rate limit)
        |
        v
   Backend: recuperacion RAG (LanceDB) + prompt endurecido
        |
      ┌─┴───────────────┬────────────────┐
      v                 v                v
 HF Space           Ollama local      Claude
 (prosa)            (estructurada)    (estructurada)
      |                 |                |
      └────────┬────────┴────────────────┘
               v
   Validacion Pydantic + atribucion de fuentes
               |
               v
   [ Interpretacion estructurada en pantalla ]
   hallazgos · diferenciales con citas · derivacion
```

El prompt ya no se construye en el navegador: vive en el servidor (`app/ai/prompt.py`), que
es también quien decide la ruta de modelo y quien valida la respuesta antes de devolverla.

---

## Instalacion

### 1. Requisitos

* Node 22+ (frontend Vite + TypeScript)
* Python 3.12 y [uv](https://docs.astral.sh/uv/) (backend FastAPI)
* Opcional: [Ollama](https://ollama.com) para la ruta de IA auto-alojada

### 2. Variables de entorno

Copiar `backend/.env.example` a `backend/.env` y rellenarlo. Nunca va bajo la raiz servida
ni al repositorio; en HF Spaces se usan los *Secrets* del Space en su lugar.

### 3. Base de datos

Se crea sola al arrancar: SQLite en `instance/morphos.db`, fuera de la raiz servida. Con
`MORPHOS_MYSQL_DSN` definido se usa MySQL/MariaDB en su lugar.

### 4. Iniciar la aplicacion

```bash
make frontend-install && make frontend-build   # SPA → dist/
make backend-sync && make dev                  # FastAPI en http://localhost:8000
```

## Backend de IA

La ruta la decide el **servidor** (`MORPHOS_IA_BACKEND_DEFECTO`), no el navegador: asi la
eleccion de proveedor no depende del `localStorage` de cada cliente.

| Ruta                   | Como se activa                                | Salida        | Citas |
| ---------------------- | --------------------------------------------- | ------------- | ----- |
| medGemma en HF Space   | `medgemma` + `MORPHOS_HF_SPACE_URL` definida  | prosa libre   | Si, por marcador `[n]` |
| medGemma en Ollama     | `medgemma` + `MORPHOS_HF_SPACE_URL` vacia     | estructurada  | Si, por diferencial |
| Claude                 | `claude` + `MORPHOS_ANTHROPIC_API_KEY`        | estructurada  | Si, por diferencial |

En las tres, las **fuentes las construye el servidor** a partir de los fragmentos que la
recuperacion entrego de verdad; una cita que no se resuelve contra un fragmento real se
descarta antes de llegar al veterinario.

### Ruta auto-alojada con Ollama

Es la unica ruta que escala para una herramienta gratuita: el Space con ZeroGPU rinde del
orden de **4 analisis por dolar** de cuota, mientras que en local el coste marginal por
analisis es la electricidad. Ademas da salida **estructurada** (el Space solo puede devolver
prosa), que es lo que permite diferenciales con probabilidad, evidencia y citas por separado.

```bash
# 1. Instalar y arrancar Ollama
brew install ollama            # o https://ollama.com/download
ollama serve

# 2. Descargar el modelo clinico
ollama pull medgemma           # ajusta la etiqueta a la variante que uses

# 3. Apuntar el backend a Ollama vaciando la URL del Space
#    (en backend/.env)
MORPHOS_IA_BACKEND_DEFECTO=medgemma
MORPHOS_HF_SPACE_URL=
MORPHOS_MEDGEMMA_BASE_URL=http://localhost:11434
MORPHOS_MEDGEMMA_MODEL=medgemma:latest
```

Notas de despliegue:

* **Hardware**: una variante de 4B corre en CPU con paciencia; para tiempos de respuesta
  aceptables con imagenes de citologia conviene GPU con 8 GB+ de VRAM.
* **En red**: si Ollama corre en otra maquina de la LAN, arrancalo con
  `OLLAMA_HOST=0.0.0.0 ollama serve` y pon esa IP en `MORPHOS_MEDGEMMA_BASE_URL`. Ollama no
  tiene autenticacion: dejalo detras del firewall de la clinica, nunca expuesto a internet.
* **Contrato identico**: el cliente (`app/ai/medgemma.py`) pasa el JSON Schema de
  `InterpretacionClinica` en el campo `format`, asi que la respuesta valida contra Pydantic
  sin ninguna limpieza por regex.
* **Sin red durante la inferencia**: los datos del paciente no salen de la clinica, que es
  el argumento de privacidad de la herramienta.

El mismo Ollama sirve ademas de **juez gratuito** para las evals (ver `evals/README.md`).

---

## Motor de deteccion de patrones

`frontend/src/analisis.ts` compara cada valor ingresado contra los rangos de referencia del JSON, ajustados dinamicamente segun:

* **Especie**: canino / felino
* **Edad**: cachorro, adulto, senior, geriatrico
* **Raza**: galgo/whippet (RBC y plaquetas), Shiba/Akita (RBC)
* **Sexo**: felinos machos tienen mayor tolerancia a creatinina

La gravedad se calcula como la desviacion relativa al ancho del rango de referencia. Con los hallazgos se identifican mas de 50 patrones clinicos (anemias, hepatopatias, nefropatia, alteraciones endocrinas, electrolitos, entre otros).

El motor está congelado por una suite de regresión (`frontend/tests`, Vitest) que se ejecuta
con `make frontend-test`. Es la red que permite tocar el resto del stack sin cambiar
silenciosamente un criterio clínico.

---

## Calidad y evaluación

La parte clínica no se valida "a ojo": hay una puerta de CI que bloquea el merge ante una
regresión (`.github/workflows/evals.yml`).

```bash
make frontend-test    # regresión del motor determinista
make backend-test     # pruebas del backend (esquemas, prompt, RAG, citas, seguridad)
make evals            # evals clínicas: puerta con tolerancia cero a fallos de seguridad
make revision         # hoja de revisión veterinaria de los casos aún sin firmar
```

Las evals miden recall de diferenciales, cobertura de hallazgos, acierto de derivación,
idioma y seguridad, y añaden una rúbrica de juez LLM que corre **en local y gratis** sobre
Ollama. El dataset separa un split reservado y sólo cuenta para la puerta los casos con
validación veterinaria firmada. Detalle en `evals/README.md`.

---

## Seguridad aplicada

* Sesiones firmadas con cookie `HttpOnly` / `SameSite` / `Secure`, y CSRF de doble token
* Contraseñas hasheadas con **scrypt** y comparación en tiempo constante
* Consultas parametrizadas (sin interpolacion directa)
* `/api/interpret` y `/api/papers` exigen sesión: no hay acceso anónimo al modelo
* Rate limiting por IP **y por usuario** (la cuota de GPU es compartida entre veterinarios)
* CORS restringido a orígenes conocidos, nunca `*`
* Cabeceras de seguridad: CSP estricta, HSTS en producción, `nosniff`, `frame-ancestors none`
* Claves de API sólo en el servidor (`backend/.env` o secrets del Space), jamás en el cliente
* BD de usuarios e índice RAG **fuera de la raíz servida** (`instance/`), no descargables
* Validación en servidor de las imágenes de citología (número, tipo MIME y tamaño)
* Texto del modelo y de APIs externas insertado con escapado, sin `eval` ni `document.write`

---

## Conceptos del curso aplicados

* HTML5 semantico
* CSS personalizado: variables, fuentes fluidas, grid, flexbox, media queries, temas claro/oscuro
* JavaScript/TypeScript: ES Modules, `fetch`, `async/await`, eventos, DOM API, tipos estrictos
* Python: FastAPI, Pydantic, `async`/`await`, gestión de dependencias con uv
* Bases de datos: creacion de tablas, consultas con parametros, indices unicos (SQLite o MariaDB)

---

## Mejoras futuras

* Implementación de dashboard de administrador
* Desarrollo de extensión de navegador para captar datos del DOM de PIMS y obtener los datos de los analisis de los pacientes con intervención mínima del usuario
* Desarrollo de mobile app dedicada
* Integración con PIMS más utilizados en veterinaria
* Rankeo de papers basado en confiabilidad y relevancia
* Creación de Dataset específico para citologías de animales
* Hosting del modelo en VPS serverless para finetuning y menor latencia
* Ampliación de la base de alteraciones
* Parseo con OCR de fotografías de analíticas
* Incluir resultados de gasometría, coprologías, informes de histopatologías y tiempos de coagulación

## Retos

* Por la diversidad de unidades de medición que utilizan los diferentes fabricantes de equipos de laboratorio se incorporó una detección de unidades para su conversión y normalización
* El modelado del output de la I.A requirió muchísimas iteraciones de formateo del prompt y harness para evitar alucinaciones o que envíara su proceso de pensamiento, aún requiere de mucho trabajo extra de refinamiento
* Inicialmente quería usar proveedores de inferencia gratuita de medGemma (como featherless AI) pero fallaban continuamente, por eso decidí optar por hostear al modelo en Zero GPU de HF con la subscripción pro para la prueba de concepto
* Incluir las librería de parseo de pdf y las fuentes en el directorio del proyecto con la intención de reducir dependencias externas estaba generando problemas con las métricas de velocidad de lighthouse que no lograba solucionar. Claude planteó implementación de caché en htacesss y pre carga de las fuentes, lo cual llevó la puntuación de 60 a 90/100 sin mayores cambios estructurales
* Lograr una interfaz limpia y entendible requirío de muchos intentos hasta lograr un flujo de trabajo intuitivo y accsesible con la mínima friccion posible para los usuarios
* La API de PubMed sólo admite input en inglés, así que implementó un objeto con traducciones de los patrones clínicos más comúnes para poder realizar las peticiones

## Notas

* La base de datos se crea sola al arrancar; no hay ningún script de instalación que borrar
* El parser de PDF funciona completamente en el navegador (sin subida al servidor) para evitar enviar información privada al modelo de IA.
* La busqueda de literatura filtra los patrones detectados, los traduce al ingles y consulta PubMed via `esearch` + `esummary`
* El corpus de libros con licencia y el índice RAG nunca entran en git: se distribuyen por
  datasets privados del Hub (`make fetch-index`) y se hornean en la imagen de despliegue