Saltar al contenido
vfernandezg.devProyectosContacto
Todos los proyectos

HumanAIz

Verificación de descansos médicos asistida por IA, primer puesto en la Hackathon de Grupo Rocío. La IA lee el certificado, reglas en código lo validan y Recursos Humanos decide.

Pantalla de ingreso de HumanAIz, con la etiqueta de proyecto ganador del primer puesto en la Hackathon de Grupo Rocío, el título Verificación de descansos médicos asistida por inteligencia artificial, el acceso a la demostración y un certificado de ejemplo con su lectura con IA
Rol
Hackathon de dos días en equipo, primer puesto; después reescribí la versión actual por mi cuenta
Periodo
nov 2025
Estado
Completado
Tecnologías
  • FastAPI
  • Python
  • PostgreSQL
  • React
  • TypeScript
  • Tailwind CSS
  • Docker

HumanAIz nació en la Hackathon de Grupo Rocío, dos días de noviembre de 2025. El reto era que una IA leyera un certificado de descanso médico y diera su análisis de si era válido, como apoyo a quien lo revisa y sin decidir por nadie. Nuestro equipo obtuvo el primer puesto, y ese resultado fue además mi puerta de entrada a Grupo Rocío.

El prototipo de esos dos días estaba armado con un generador de aplicaciones, Supabase y un flujo de n8n. Más adelante lo reescribí por completo por mi cuenta para dejarlo en condiciones, con backend propio, y lo publiqué como demo abierta en español e inglés, con cuentas de prueba y solo datos ficticios.

La hackathon

Fueron dos días para construir el prototipo y presentarlo. La premiación fue el 22 de noviembre de 2025.

El equipo trabajando alrededor de una mesa con portátiles durante la hackathon, en una sala con más equipos al fondo Un integrante del equipo presenta la propuesta frente a una pantalla con el título Nuestra propuesta de valor y la aplicación HumanAIz, mientras el resto del equipo espera a un lado junto a los banners de Grupo Rocío Pantalla de la premiación de la Hackathon de Grupo Rocío con el podio: Human AIz en el primer puesto, Laborable en el segundo y Ross IA en el tercero El equipo, cinco personas, sonriendo detrás de un trofeo de cartón con el número 1

Cómo funciona

Diagrama del funcionamiento. El colaborador sube la foto del certificado a un servicio en FastAPI, que la valida y la vuelve a codificar, la lee con IA y aplica 13 reglas en código; el analista de Recursos Humanos recibe una sugerencia y decide. La lectura es el único paso que sale del servicio, hacia el proveedor de IA y con la clave del usuario. Debajo, los cinco pasos de una lectura: clave, cliente, campos, reglas y resultado Diagrama del funcionamiento. El colaborador sube la foto del certificado a un servicio en FastAPI, que la valida y la vuelve a codificar, la lee con IA y aplica 13 reglas en código; el analista de Recursos Humanos recibe una sugerencia y decide. La lectura es el único paso que sale del servicio, hacia el proveedor de IA y con la clave del usuario. Debajo, los cinco pasos de una lectura: clave, cliente, campos, reglas y resultado

  1. El colaborador sube una foto o captura de su certificado. No escribe fechas ni datos.
  2. Él o el analista de Recursos Humanos pueden pedir una lectura con IA, cada uno con su propia clave.
  3. Recursos Humanos revisa el documento y la lectura, confirma las fechas y aprueba o rechaza.

En la bandeja de Recursos Humanos, la sugerencia de la lectura aparece junto al estado, que siempre lo decide una persona:

Bandeja de solicitudes de Recursos Humanos con tres certificados de ejemplo: uno aprobado cuya lectura no tuvo observaciones, uno pendiente con lectura para revisar y uno rechazado con problemas

La IA lee, el código decide

El modelo recibe la imagen y devuelve campos contra un esquema estricto: DNI, nombre, fechas, días, contingencia, número de CITT y colegiatura del médico. No emite veredicto. Las 13 comprobaciones las hace código puro, con pruebas, y distinguen lo crítico de lo informativo: que el DNI coincida con el de la ficha es crítico; que los días indicados cuadren con las fechas o que figure la colegiatura del médico solo invita a revisar.

El resultado es una de tres sugerencias: sin observaciones, para revisar o con problemas. La lectura no modifica el descanso, y las fechas leídas se proponen para que Recursos Humanos las confirme. Ningún texto del documento se copia al resultado, así que un certificado con instrucciones escritas no puede influir en él.

Esta es una lectura real sobre uno de los certificados ficticios de la demo, el que trae inconsistencias a propósito: indica cinco días para un periodo de tres y no lleva la colegiatura del médico.

Detalle de un descanso con el certificado ficticio a la izquierda y la lectura con IA a la derecha. El resultado es Para revisar, con 13 comprobaciones de las que dos tienen observaciones: los días indicados no coinciden con las fechas y no se lee la colegiatura del médico. Debajo, los datos que leyó la IA y el modelo usado

En una prueba del 15 de noviembre de 2026, las tres variantes de ejemplo dieron el resultado esperado y cada lectura tardó entre 3 y 5 segundos.

Con tu propia clave

La demo no tiene una clave central de IA. Quien pide una lectura usa la suya, de cualquiera de siete proveedores, y el consumo va a su cuenta.

Diálogo Tu clave de IA, con el campo para pegar la clave, el proveedor Anthropic detectado, los modelos sugeridos y el aviso de que la clave no se guarda

  • La clave no se guarda. Vive en la memoria de la pestaña, viaja en una cabecera en cada petición y la API crea el cliente del proveedor solo para esa petición. Se guarda únicamente el resultado.
  • La URL de cada proveedor está fija en el código. El usuario elige el modelo, nunca el servidor al que se envía su documento.
  • Nada la registra. El proxy y la API no registran cabeceras, los errores no devuelven lo recibido y una política de seguridad de contenido estricta deja fuera los scripts de terceros.
  • Un test canario lo comprueba. Envía una clave falsa reconocible por todo el sistema y después la busca en las respuestas, los logs, un volcado completo de la base de datos y el volumen de archivos.

Queda un límite que el código no puede eliminar: mientras dura la llamada, la clave está en la memoria del proceso de la API.

Una demo pública que acepta archivos

  • Solo imágenes, y solo una copia limpia. El tipo se decide por los bytes iniciales, no por el nombre. Un proceso aislado decodifica la imagen con límite de tiempo, memoria y píxeles y la vuelve a codificar; el original se descarta, con lo que llevara escondido.
  • Sin URL públicas. Toda imagen pasa por un endpoint que comprueba quién la pide, cada navegador solo ve lo que subió él mismo y todo caduca a las 24 horas.
  • Límites en capas. Por usuario, por IP y un tope total común, que es el que protege al servidor cuando alguien cambia de IP.
  • Certificados de ejemplo. La demo genera certificados ficticios con marca de agua para probar la lectura sin usar documentos reales.

Calidad y entrega

  • Pruebas. 162 tests en el backend, entre unitarios, de integración sobre un PostgreSQL real con el proveedor simulado y de extremo a extremo sobre el stack completo, y 45 en el frontend. Ninguno usa una clave real.
  • Contrato. El frontend genera sus tipos desde el OpenAPI de la API, y un test falla si el contrato guardado deja de coincidir.
  • CI. GitHub Actions ejecuta lint, formato, migraciones y tests del backend, y lint, tipos, tests y build del frontend.
  • Despliegue. En un servidor propio corre con Docker Compose: Caddy, la API y PostgreSQL. La demo pública usa una sola imagen en Vercel con PostgreSQL en Neon, y su infraestructura está definida con Terraform en un repositorio aparte.

De la hackathon a la versión actual

  • De un frontend generado, Supabase y un flujo de n8n a FastAPI, PostgreSQL y React en contenedores, sin dependencias propietarias.
  • De un veredicto que salía del flujo de IA a reglas en el repositorio, con pruebas.
  • De una clave central a la clave de cada usuario, que no se almacena.
  • De no tener pruebas a 207 tests y CI.

Límites

  • Las reglas son una reconstrucción, porque el flujo original no se pudo recuperar. Antes de darles peso hay que revisarlas con Recursos Humanos.
  • No consulta EsSalud ni el Colegio Médico: comprueba que el CITT y la colegiatura figuren, no que sean auténticos.
  • No hay moderación automática del contenido de las imágenes; lo cubren los términos de uso y la caducidad.
  • Los certificados médicos son datos sensibles. La demo solo admite datos ficticios, y un uso real exigiría definir antes la base legal y la conservación de los documentos.