Spaces:

blackmistcode
/

morphos

Running

App Files Files Community

morphos / README.md

Jose Salazar

README al día con el estado real del código

fbec6dd 13 days ago

preview code

Raw

History Blame Contribute Delete

20.5 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 hoy no dispone de herramientas de este tipo gratuitas, de uso sencillo y capaces de dar información complementaria relevante en muy poco tiempo.

Qué sale del navegador y qué no. El esquema de la petición (PacienteEntrada) admite únicamente especie, raza, edad y sexo: no existe ningún campo para el nombre del animal ni para datos del propietario, así que no es una política sino una imposibilidad estructural. A eso se suman los valores de laboratorio y, si las hay, imágenes de citología o microscopía: campos de microscopio, sin identificadores. El PDF original nunca se sube: se parsea entero en el navegador.

El único campo de texto libre es «signos clínicos». Hoy viaja tal cual —el servidor lo inspecciona para la guarda de alcance, pero no lo filtra—, así que es el único sitio donde alguien podría teclear algo identificativo. Está previsto acotarlo a vocabulario clínico (ver Mejoras futuras).

Con la ruta auto-alojada (Ollama en la clínica) no sale nada en absoluto: ver más abajo.

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 (tiempo real, en el navegador)
    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
    src/lab-import.ts→ importación desde analizadores (cola de muestras y emparejado)
    src/panel-vacio.ts→ estado vacío de los paneles de exámenes (escritorio)
    src/form-inject.ts→ base común de los importadores (PDF y analizador)
    tests/           → suite de regresión del motor y del parser de PDF (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/motor/       → suelo de seguridad recalculado en servidor (rangos y gravedad)
    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
    ajustes_clinicos.json   → umbrales de gravedad, cortes clínicos, ajustes por edad/raza e IRIS
                              (única fuente de verdad: la leen los DOS motores)
    alteraciones.json       → descripciones clínicas de los patrones
    lab_mapeos/             → códigos de prueba → analito canónico, por fabricante
    rag_alcance.json        → qué páginas del corpus entran y con qué especie

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

/instance            → índice RAG y BD de usuarios si no hay volumen persistente; 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 y el esquema se migra solo (PRAGMA user_version; ver _MIGRACIONES en backend/app/db.py). Es SQLite, siempre fuera de la raiz servida:

Si hay un volumen persistente montado en /data, la BD vive ahí y sobrevive a los reinicios.
Si no, cae a instance/morphos.db, que en HF Spaces es efímero: cada reinicio borra cuentas, contraseñas e historial de intentos. Se avisa por log al arrancar.

Se puede forzar la ruta con MORPHOS_DB_PATH. No hay soporte de MySQL/MariaDB: existieron variables MORPHOS_MYSQL_* que ningún código leía y se eliminaron.

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 (p. ej. el fosforo del cachorro, sin el cual todo animal en crecimiento sale hiperfosforemico)
Raza: lebreles —galgo, greyhound, whippet, saluki…— en serie roja, plaquetas, creatinina y T4 (sin ese ajuste, ~90 % de los galgos sanos salen hipotiroideos); razas asiaticas (shiba, akita, chow, shar pei) en VCM, que es microcitosis fisiologica sin anemia; Maine Coon y Birman en felinos
Sexo: sin ajustes. El que habia —mas tolerancia a creatinina en el gato macho— se retiro por no tener respaldo en el corpus: toleraba un 15 % mas justo en la poblacion con mas ERC

La gravedad se mide como desviacion relativa al ancho del rango, salvo donde esa regla no sabe expresar la clinica: hematocrito y plaquetas por lo bajo, y creatinina, SDMA y UP/C por lo alto, tienen cortes explicitos (con rango 24-45, un gato necesitaria un hematocrito negativo para llegar a «grave»). Con los hallazgos se identifican mas de 50 patrones clinicos (anemias, hepatopatias, nefropatia, alteraciones endocrinas, electrolitos, entre otros) y el estadiaje IRIS de ERC.

Las reglas clinicas son datos, no codigo. Umbrales, cortes, limites de edad, factores por raza y cortes IRIS viven en data/ajustes_clinicos.json, con su procedencia bibliografica, y los leen por igual el motor del navegador y el del servidor. Un veterinario puede revisarlos y ajustarlos sin desarrollador ni build.

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 exige sesión: no hay acceso anónimo al modelo. /api/papers no la exige a propósito (búsqueda en PubMed, ni sensible ni cara); lo acota el rate limiting
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
Alta de cuentas cerrada por lista blanca de emails (MORPHOS_REGISTRO_ALLOWLIST): una cuenta alcanza el modelo, así que el alta abierta era una autorización de gasto para cualquiera
Resultados de analizador aislados por clínica: el tenant lo pone el servidor —de la API key del dispositivo al ingerir, de la cookie firmada al leer—, nunca el cuerpo de la petición. Una muestra de otra clínica responde 404, no 403
Sesiones revocables: el logout invalida el token de verdad (no sólo borra la cookie) y /api/auth/logout-todas cierra la sesión en todos los dispositivos
El suelo de seguridad se recalcula en el servidor: los hallazgos y su gravedad se derivan de los valores crudos (app/motor/gravedad.py), así que omitir o falsear el veredicto del cliente ya no relaja la derivación obligatoria. Lo que afirma el navegador sólo puede endurecerla
Rate limiting consciente del proxy inverso (MORPHOS_PROXY_SALTOS_CONFIABLES): detrás de un proxy, request.client.host es el proxy y los límites «por IP» serían en realidad globales

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 y migraciones versionadas (SQLite)

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
Filtrado del campo «signos clínicos» contra una lista de términos clínicos permitidos, para que ni datos identificativos ni texto arbitrario lleguen al modelo
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