From 8e6b05bf2823eaa0a41bfc1a60c658f6d5762826 Mon Sep 17 00:00:00 2001 From: Maximo Gomez Date: Sat, 6 Jun 2026 14:15:05 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 318 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 316 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1f15427..b975082 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,317 @@ -# ai-interview-scorer +# interview-scorer -Sistema automatizado que graba entrevistas de selección, genera un transcript y produce un scorecard ponderado por competencias con evidencia STAR — eliminando la evaluación manual inconsistente en los 14 países de GLM. \ No newline at end of file +> Sistema automatizado que graba entrevistas de seleccion, genera un transcript y produce un scorecard ponderado por competencias con evidencia STAR — eliminando la evaluacion manual inconsistente en los 14 paises de GLM. + +--- + +## Informacion General + +| Campo | Detalle | +|---|---| +| Proyecto | Interview Scorer | +| Area | RRHH | +| Estado | En Progreso | +| Developer Principal | Isaac Aracena | +| IT Manager | Luis Matos | +| Fecha de Inicio | 2026-06-16 | +| Fecha de Cierre Estimada | 2026-07-27 | +| Ciclo Shape Up | Ciclo #2 — Semana 1 de 6 | +| Board de Ejecucion | [Link a Kan.bn — completar al crear el board] | +| PRD | [Link al PRD — completar] | + +--- + +## Objetivo + +### Problema que resuelve + +Los coordinadores de RRHH en los 14 paises de GLM evaluan candidatos en Excel o por email sin una estructura homogenea. No existe una metodologia de scoring consistente entre los aproximadamente 20 entrevistadores del equipo. El resultado son evaluaciones incomparables entre paises, riesgo de contrataciones incorrectas y sin historial centralizado de candidatos. Maximo tiene un workflow personal con Fireflies y Claude que produce scorecards de calidad, pero es manual y no se ha podido escalar. + +### Solucion implementada + +Pipeline automatizado en n8n que convierte cualquier entrevista de seleccion en un scorecard estructurado con metodologia STAR y score ponderado por competencia, sin intervencion manual del entrevistador. Opera en dos canales: + +- Canal virtual: un bot se une automaticamente a la reunion de Google Meet, graba el audio y al finalizar dispara el pipeline. +- Canal presencial: el coordinador graba el audio desde su celular y sube el archivo. El pipeline continua de forma identica. + +En ambos casos el sistema transcribe el audio, lee el JD y la rubrica del puesto desde el catalogo en Supabase, genera el scorecard con Claude o Gemini, lo envia por Gmail al entrevistador y almacena el registro completo en Supabase. + +### Usuarios / Beneficiarios + +- Operan el sistema: 20 coordinadores de RRHH en 14 paises. Para entrevistas virtuales no realizan ninguna accion adicional. Para presenciales solo suben el archivo de audio. +- Reciben el output: el coordinador que realizo la entrevista recibe el scorecard por email. +- Consultan el historial: Luis Matos y Maximo Gomez via Supabase. + +--- + +## Arquitectura + +### Diagrama de flujo + +Canal virtual: + +``` +Reunion Google Meet agendada desde cuenta GLM + → Bot de sala se une automaticamente al inicio + → Bot graba el audio durante la entrevista + → Al cerrar la reunion, n8n recibe el archivo de audio + → Motor de transcripcion convierte audio a transcript con diarizacion (Entrevistador / Candidato) + → n8n consulta catalogo en Supabase: lee JD y rubrica del puesto + → Claude o Gemini analiza transcript + JD + rubrica y genera el scorecard + → n8n formatea scorecard en HTML y genera PDF adjunto + → Gmail envia el scorecard al entrevistador + → Supabase almacena scorecard completo con metadata +``` + +Canal presencial: + +``` +Coordinador graba la entrevista desde su celular + → Coordinador sube el archivo de audio al sistema + → n8n recibe el archivo e inicia el pipeline + → Continua identico al canal virtual desde el paso de transcripcion +``` + +### Stack tecnologico + +| Componente | Tecnologia | Proposito | +|---|---|---| +| Automatizacion | n8n | Orquestacion del flujo completo | +| Motor de IA / Scoring | Claude o Gemini (a definir — ver DECISIONS.md DEC-002) | Analisis del transcript y generacion del scorecard | +| Transcripcion de audio | A definir: Google Speech-to-Text / Whisper / Fireflies (ver DECISIONS.md DEC-001) | Conversion de audio a transcript con diarizacion | +| Base de datos | Supabase / Postgres | Catalogo de puestos, scorecards e historial de candidatos | +| Infraestructura | Google Cloud / Servidor Virtual | Hosting y ejecucion | +| Captacion de Meet | Google Meet API / Bot de sala | Grabacion automatica de entrevistas virtuales | +| Notificaciones | Gmail via n8n | Envio del scorecard al entrevistador | + +### Integraciones externas + +| Sistema | Tipo de integracion | Datos que fluyen | +|---|---|---| +| Google Meet | API / Bot de sala | Audio de la entrevista virtual grabado por el bot | +| Motor de transcripcion (a definir) | API REST | Audio de entrada / transcript con diarizacion de salida | +| Supabase | SDK / SQL | Lectura del catalogo de puestos y escritura de scorecards | +| Gmail | OAuth / n8n | Envio del scorecard final al entrevistador con PDF adjunto | + +--- + +## Configuracion y Setup + +### Prerequisitos + +- [ ] Cuenta de servicio Google con acceso a Google Meet API configurada +- [ ] Motor de transcripcion seleccionado y API key activa (ver DECISIONS.md DEC-001) +- [ ] Claude API key o Gemini API key configurada (ver DECISIONS.md DEC-002) +- [ ] Base de datos Supabase creada con schema aplicado (ver /docs/schema.sql) +- [ ] Catalogo de puestos poblado en Supabase con JDs y rubricas activas +- [ ] Credenciales Gmail OAuth configuradas en n8n +- [ ] Workflows de n8n importados desde /n8n/ + +### Variables de entorno + +| Variable | Descripcion | Donde se obtiene | +|---|---|---| +| `TRANSCRIPTION_API_KEY` | API Key del motor de transcripcion seleccionado | Panel del proveedor elegido | +| `TRANSCRIPTION_PROVIDER` | Proveedor activo: google / whisper / fireflies | Definido en DECISIONS.md DEC-001 | +| `AI_SCORING_KEY` | API Key de Claude o Gemini | Anthropic Console / Google AI Studio | +| `AI_SCORING_PROVIDER` | Motor de scoring: claude / gemini | Definido en DECISIONS.md DEC-002 | +| `SUPABASE_URL` | URL de conexion a Supabase | Supabase → Settings → API | +| `SUPABASE_KEY` | Service role key de Supabase | Supabase → Settings → API | +| `GMAIL_CLIENT_ID` | OAuth Client ID de Gmail | Google Cloud Console | +| `GMAIL_CLIENT_SECRET` | OAuth Client Secret de Gmail | Google Cloud Console | +| `N8N_WEBHOOK_MEET` | Webhook que recibe el audio del bot de Google Meet | n8n → Workflow settings | +| `N8N_WEBHOOK_PRESENCIAL` | Webhook que recibe el archivo de audio presencial | n8n → Workflow settings | + +> NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM. + +### Instalacion / Deploy + +```bash +# Clonar el repo +git clone https://gitea.glm.com/glm-it/interview-scorer + +# Instalar dependencias +pip install -r requirements.txt + +# Configurar variables de entorno +cp .env.example .env +# Editar .env con las credenciales reales + +# Aplicar schema de base de datos +psql $SUPABASE_URL < docs/schema.sql + +# Importar workflows de n8n +# n8n → Settings → Import workflow → seleccionar archivos en /n8n/ + +# Verificar conexion a todos los servicios +python src/health_check.py +``` + +--- + +## Como funciona + +### Flujo paso a paso + +1. Trigger canal virtual: el bot de Google Meet se une automaticamente a la reunion al inicio. Al cerrarse, el bot envia el archivo de audio a n8n via webhook POST a `N8N_WEBHOOK_MEET`. +2. Trigger canal presencial: el coordinador sube el archivo de audio manualmente al endpoint `N8N_WEBHOOK_PRESENCIAL`. El nombre del archivo o un campo adicional indica el puesto. +3. Identificacion del puesto: n8n extrae el nombre del puesto del evento de calendario (canal virtual) o del nombre del archivo (canal presencial) y consulta el catalogo en Supabase para obtener el JD y la rubrica. +4. Transcripcion: el archivo de audio se envia al motor configurado. El resultado es un transcript con diarizacion: cada turno identificado como Entrevistador o Candidato. +5. Scoring con IA: el transcript, el JD y la rubrica se envian al motor de IA. El modelo genera score ponderado por competencia, evidencia STAR extraida del transcript, fortalezas observadas, riesgos con nivel (Alto/Medio/Bajo), preguntas para segunda entrevista si el score esta entre 2.5 y 3.9, y recomendacion final. +6. Generacion del scorecard: n8n formatea el output en HTML con identidad visual GLM y genera un PDF adjunto. +7. Envio: Gmail envia el scorecard al entrevistador con el reporte en el cuerpo del correo y el PDF adjunto. +8. Almacenamiento: Supabase registra el scorecard completo con metadata: candidato, puesto, cliente, pais, entrevistador, fecha, score final y decision recomendada. + +### Schedules / Triggers + +| Trigger | Frecuencia | Descripcion | +|---|---|---| +| Webhook POST /meet-audio | On demand | Disparado por el bot al cerrar la reunion de Google Meet | +| Webhook POST /audio-upload | On demand | Disparado por el coordinador al subir audio de entrevista presencial | + +--- + +## Testing + +### Como probar el sistema + +```bash +# Test unitario del motor de scoring +python -m pytest tests/test_scoring.py + +# Test de integracion del pipeline completo con audio de prueba +python tests/integration_test.py --audio tests/fixtures/entrevista_prueba.mp3 --puesto mercaderista-nic + +# Test manual en n8n +# Canal virtual: abrir workflow_virtual → Execute workflow con audio de prueba +# Canal presencial: abrir workflow_presencial → Execute workflow con archivo de audio local +``` + +### Casos de prueba minimos + +| Caso | Input | Output esperado | Estado | +|---|---|---|---| +| Entrevista virtual completa | Audio de Meet con dos voces claras | Scorecard completo con score ponderado y evidencia STAR por competencia | Pendiente | +| Entrevista presencial completa | Archivo MP3 subido manualmente con puesto en el nombre | Scorecard identico al canal virtual | Pendiente | +| Puesto no encontrado en catalogo | Audio con nombre de puesto invalido | Error manejado, notificacion al entrevistador pidiendo aclaracion | Pendiente | +| Audio con mala calidad | Archivo con ruido de fondo alto | Transcript generado con advertencia de calidad baja | Pendiente | +| Motor de transcripcion caido | Timeout en llamada al API | Retry automatico x3, alerta a Luis Matos si persiste | Pendiente | +| Motor de scoring caido | Timeout en llamada a Claude / Gemini | Retry automatico x3, alerta a Luis Matos si persiste | Pendiente | + +--- + +## Errores conocidos y troubleshooting + +| Error | Causa probable | Solucion | +|---|---|---| +| Scorecard no llega al entrevistador | Credenciales Gmail vencidas o webhook caido | Revisar logs en n8n → Executions. Renovar OAuth token en n8n → Credentials | +| Transcript vacio o ilegible | Audio de mala calidad o error en el motor de transcripcion | Revisar logs del nodo de transcripcion en n8n. Probar con audio limpio. Verificar API key del proveedor | +| Puesto no encontrado en catalogo | Nombre del puesto en el evento o archivo no coincide con el catalogo | Verificar tabla de puestos en Supabase. Actualizar catalogo o corregir el nombre del evento / archivo | +| Score incorrecto o sin evidencia | Transcript con diarizacion incorrecta o prompt degradado | Verificar que el transcript distingue Entrevistador / Candidato. Ejecutar test_scoring.py con el transcript en cuestion | +| Bot no se une a la reunion de Meet | Reunion creada desde cuenta externa o con sala de espera activa | Verificar que la reunion fue agendada desde cuenta GLM. Desactivar sala de espera para el bot | +| 401 Unauthorized en Supabase | Service role key vencida o incorrecta | Renovar key en Supabase → Settings → API y actualizar .env | + +--- + +## Monitoreo + +- n8n Executions: revisar logs diariamente en n8n → Executions. Cualquier ejecucion fallida genera alerta a Luis Matos por email. +- Supabase: verificar semanalmente que los registros de scorecards se estan guardando correctamente con metadata completa. +- Calidad del scoring: Maximo revisa aleatoriamente 2 scorecards por semana durante el primer mes para validar que la calidad se mantiene equivalente al benchmark manual. +- Output esperado en condiciones normales: cada entrevista procesada produce un scorecard enviado al entrevistador dentro de los 10 minutos siguientes al cierre de la reunion o la subida del audio. + +--- + +## Estructura del repositorio + +``` +/interview-scorer +├── README.md <- Este archivo +├── .env.example <- Variables de entorno de ejemplo sin valores reales +├── requirements.txt <- Dependencias Python +├── /src +│ ├── health_check.py <- Verifica conexion a todos los servicios configurados +│ ├── transcription.py <- Cliente del motor de transcripcion (abstrae el proveedor) +│ ├── scoring.py <- Prompt de scoring y llamada al motor de IA +│ ├── scorecard_renderer.py <- Generacion del HTML y PDF del scorecard +│ └── catalog.py <- Lectura del catalogo de puestos desde Supabase +├── /n8n +│ ├── workflow_virtual.json <- Flujo canal Google Meet +│ └── workflow_presencial.json <- Flujo canal presencial (subida de audio) +├── /tests +│ ├── test_scoring.py <- Tests unitarios del motor de scoring +│ ├── integration_test.py <- Test end-to-end del pipeline completo +│ └── /fixtures +│ └── entrevista_prueba.mp3 <- Audio de prueba para tests +├── /docs +│ ├── schema.sql <- Schema de Supabase: tabla catalogo y tabla scorecards +│ └── architecture.png <- Diagrama de arquitectura del sistema +├── CHANGELOG.md <- Historial de cambios por version +└── DECISIONS.md <- Log de decisiones tecnicas (DEC-001 motor transcripcion, DEC-002 motor IA) +``` + +--- + +## CHANGELOG + +``` +[2026-07-27] v1.0 — Launch inicial — pipeline completo con canal virtual y presencial +``` + +--- + +## DECISIONS LOG + +### DEC-001 — Motor de transcripcion + +- Fecha: A completar por Isaac Aracena — Semana 1 +- Contexto: El sistema requiere convertir audio de entrevistas a transcript con diarizacion (identificacion de Entrevistador vs Candidato). Se evaluaron tres opciones con audio real de entrevistas GLM. +- Opciones consideradas: Google Speech-to-Text (en stack GLM, sin licencia adicional) vs Whisper de OpenAI (precision alta, costo por uso) vs Fireflies (solucion completa con diarizacion nativa, costo por usuario) +- Criterios de evaluacion: precision en Espanol latinoamericano, calidad de diarizacion, costo por hora de audio, facilidad de integracion con n8n +- Decision: [A completar] +- Razon: [A completar] + +### DEC-002 — Motor de scoring (IA) + +- Fecha: A completar por Isaac Aracena — Semana 1 +- Contexto: El sistema requiere un modelo de lenguaje que analice el transcript junto con el JD y la rubrica para generar el scorecard con evidencia STAR. +- Opciones consideradas: Claude (Anthropic — ya en uso en GLM) vs Gemini (Google — ya en stack GLM) +- Criterios de evaluacion: calidad del razonamiento para extraccion de evidencia conductual, costo por token, latencia de respuesta +- Decision: [A completar] +- Razon: [A completar] + +--- + +## Contactos del proyecto + +| Rol | Nombre | Contacto | +|---|---|---| +| Product Owner | Maximo Gomez | mgomez@gomezleemarketing.com | +| IT Manager | Luis Matos | [email/WhatsApp] | +| Developer Principal | Isaac Aracena | [email/WhatsApp] | + +--- + +## Definition of Done + +Checklist antes de mover a Completado en Kan.bn: + +- [ ] Motor de transcripcion seleccionado, documentado en DECISIONS.md y funcionando con audio real de GLM +- [ ] Catalogo de puestos en Supabase poblado con los puestos activos +- [ ] Flujo canal virtual (Google Meet) funcionando end-to-end +- [ ] Flujo canal presencial (subida de audio) funcionando end-to-end +- [ ] Scorecard generado automaticamente validado por Maximo: 4 de 5 sin edicion +- [ ] Todos los scorecards almacenados correctamente en Supabase +- [ ] Codigo commiteado y pusheado a Gitea +- [ ] README completo y actualizado +- [ ] Variables de entorno documentadas en .env.example +- [ ] Tests basicos pasando +- [ ] Workflows de n8n exportados en /n8n/ +- [ ] CHANGELOG actualizado con v1.0 +- [ ] Probado en ambiente real con entrevistas reales (no datos simulados) +- [ ] Luis Matos valido el output tecnico +- [ ] Maximo aprobo el resultado final + +--- + +_Documento mantenido por el equipo GLM IT · Ultima actualizacion: 2026-06-16_ \ No newline at end of file