Arquitectura Técnica

Sistema multi-capa diseñado para transformar historiales clínicos heterogéneos en recursos FHIR R4 estándar, integrables en cualquier sistema de salud a nivel mundial sin modificar el sistema destino.

Capas del sistema

Frontend

  • Next.js 14 (App Router)
  • React 18 + TypeScript
  • Tailwind CSS
  • Recharts

API Gateway

  • FastAPI (uvicorn)
  • CORS + UploadFile
  • BackgroundTasks
  • Pydantic v2

Agente Fase 1 — NER

  • AgenteExtractorNER
  • Gemini 3.1 Flash Lite / Groq Llama 3.3 70B
  • MCP Tool: buscar_concepto_snomed
  • MCP Tool: validar_concepto_snomed

Agente Fase 2 — CIE-10

  • AgenteCodificadorAgentico
  • Gemini / Groq / Ollama (gemma3:4b)
  • Tool: evaluar_regla_mapeo()
  • FHIR R4 Parser

Capa de datos

  • PostgreSQL 16 (Docker)
  • IRBD SNOMED IRBD_Multibase
  • Tablas: conceptos, mapas CIE-10
  • psycopg2 + psycopg2-binary

Protocolo MCP

  • mcp_servers/snomed_server.py
  • mcp_client/snomed_client.py
  • Stdio transport (subprocess)
  • 3 tools: buscar / validar / mapeo

Flujo de homogeneización

Historial clínico (any)
POST /procesar
Agente NER + MCP SNOMED
FHIR Bundle R4 Document
Agente CIE-10 Function Calling
FHIR listo para cualquier HIS

Módulos clave del código

AgenteExtractorNER

Lee el texto libre y extrae la entidad Patient con identificadores (DNI/NUSS/NIE), y la lista jerárquica de diagnósticos (PRINCIPAL / SECUNDARIO / ANTECEDENTE) con su SNOMED CT.

fase1_homogeneizacion/nlp_extractor.py

crear_fhir_base()

Construye un FHIR R4 Bundle Document con recursos Patient y Condition usando pydantic-fhir. Cada Condition incluye la categoría clínica y la fecha de registro.

fase1_homogeneizacion/fhir_builder.py

AgenteCodificadorAgentico

Implementa Gemini Function Calling. El LLM recibe TODAS las reglas SNOMED→CIE-10 de la IRBD y llama de forma autónoma a evaluar_regla_mapeo() por cada mapGroup, decidiendo el orden de evaluación.

fase2_inferencia_cie10/rule_engine_agentic.py

MCP SNOMED Server

Servidor MCP basado en stdio que expone tres herramientas: buscar_concepto_snomed, validar_concepto_snomed y obtener_reglas_mapeo_cie10. Se lanza como subprocess desde FastAPI.

mcp_servers/snomed_server.py

IRBD PostgreSQL

Snapshot de la base de datos SNOMED IRBD_Multibase con las tablas de conceptos activos, descripciones y mapas de traducción SNOMED→ICD-10→CIE-10-ES del Ministerio de Sanidad.

database/snomed_queries.py

ProcessingResult + Graceful Degradation

Modelo de resultado con 4 niveles de confianza (HIGH/MEDIUM/LOW/MINIMAL). El pipeline continúa en modo reducido en lugar de abortar, registrando warnings para su revisión.

core/processing_result.py

¿Por qué FHIR R4 como estándar de salida?

Público → SAS / SNS

El SAS y el SNS generan expedientes en formatos propietarios que varían por comunidad autónoma, hospital o especialidad. FHIR R4 permite federar todos esos registros en un repositorio único interoperable, base de la Historia Clínica Digital del Ministerio de Sanidad.

Privado → HIS propietarios

Las clínicas privadas y mutuas operan con sistemas HIS propios cuya estructura difiere completamente del sector público. Traducir ambos al mismo FHIR R4 hace posible la continuidad asistencial cuando el paciente cambia de proveedor.

Internacional → HL7

FHIR R4 es el estándar de HL7 International adoptado por NHS (RU), ONC/CMS (EE.UU.), EU eHealth Network y la OMS. Un Bundle generado aquí es consumible en cualquiera de estos sistemas sin modificar el destino.

¿Por qué Model Context Protocol (MCP)?

Sin MCP (modo legacy)

El agente LLM llama directamente a funciones Python que consultan PostgreSQL. El LLM no “sabe” qué herramientas tiene disponibles; es el código Python el que decide cuándo y cómo llamarlas.

Con MCP (modo agéntico)

El servidor MCP expone herramientas con esquema JSON. El LLM recibe el catálogo y decide autónomamente cuándo invocar buscar_concepto_snomed o evaluar_regla_mapeo, dando lugar a un comportamiento emergente y más robusto.