Spaces:

blackmistcode
/

morphos

Sleeping

App Files Files Community

morphos / README.md

Jose Salazar

Implementacion de AI judge para evals y actualizacion de readme

1e215c9 3 days ago

preview code

Raw

History Blame Contribute Delete

16 kB

metadata

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:

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:

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

/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

[ 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 (backend FastAPI)
Opcional: Ollama 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

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.

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

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