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.

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

Cómo funciona

- El colaborador sube una foto o captura de su certificado. No escribe fechas ni datos.
- Él o el analista de Recursos Humanos pueden pedir una lectura con IA, cada uno con su propia clave.
- 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:

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.

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.

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