bamboohr-agent/README.md

# BambooHR Agent

> Agente conversacional que permite al equipo de RRHH consultar, modificar y reportar data de empleados en BambooHR mediante lenguaje natural, eliminando errores de nomina y reduciendo tiempo operativo.

---

## Informacion General

| Campo | Detalle |
|---|---|
| Proyecto | BambooHR Agent |
| Area | RRHH |
| Estado | En Progreso |
| Developer Principal | Isaac Aracena |
| IT Manager | Luis Matos |
| Fecha de Inicio | Junio 8, 2026 |
| Fecha de Cierre Estimada | Julio 19, 2026 |
| Ciclo Shape Up | Ciclo #1 — Semana 1 de 6 |
| Board de Ejecucion | https://pmit.digitalcompass.agency/boards/4inodhfrgx0h |
| PRD del Proyecto | [https://docs.google.com/document/d/1OHn7v3nZeVh94-Gm0COQ1yjkX6HrRTqWhwamH4_gOgc/edit?usp=drive_link |

---

## Objetivo

### Problema que resuelve
El equipo de RRHH (13-20 personas) gestiona toda la data de empleados entrando manualmente a BambooHR. Editar salarios, agregar empleados, desvincular, subir archivos, consultar informacion y generar reportes toma entre 5-15 minutos por operacion. Cuando hay multiples cambios pendientes, el equipo los pospone. Esos cambios olvidados llegan a nomina con datos incorrectos, generando errores que afectan al empleado, a RRHH y al area administrativa y de nomina.

### Solucion implementada
Agente conversacional conectado a BambooHR via API que recibe instrucciones en lenguaje natural por chat y las ejecuta directamente. Opera en tres modos: accion (edita, agrega, desvincula, sube archivos), consulta (responde preguntas sobre data de empleados) y reporte (genera reportes estandar y personalizados). Cada operacion queda registrada en un log de auditoria.

### Usuarios / Beneficiarios
- Operan el agente: Equipo de RRHH (13-20 personas) y equipo IT
- Acceso admin (settings de BambooHR): Solo Maximo Gomez
- Se benefician del output: Equipo administrativo, nomina y empleados GLM en 14 paises

---

## Arquitectura

### Diagrama de flujo

```
Usuario envia instruccion por chat
        |
        v
Agente valida identidad y permisos del usuario
        |
        v
Agente interpreta instruccion en lenguaje natural
        |
        +---> Modo accion  --> Ejecuta cambio en BambooHR API
        |
        +---> Modo consulta --> Extrae data de BambooHR API --> Responde en chat
        |
        +---> Modo reporte  --> Genera reporte estandar o personalizado --> Entrega en chat
        |
        v
Registro en log de auditoria (quien, que, cuando)
        |
        v
Confirmacion al usuario
```

### Stack tecnologico

| Componente | Tecnologia | Proposito |
|---|---|---|
| Agente IA | Claude / Gemini | Interpretacion de lenguaje natural y ejecucion |
| Automatizacion | n8n / Python | Orquestacion del flujo |
| Interfaz de chat | A definir por Luis Matos (WhatsApp / Google Chat) | Canal de comunicacion con el agente |
| Autenticacion | A definir por IT | Validar identidad y permisos del usuario |
| Log de auditoria | A definir por IT (Supabase / Google Sheets) | Registro de cambios |
| Infraestructura | Google Cloud / Servidor Virtual | Hosting y ejecucion |

### Integraciones externas

| Sistema | Tipo de integracion | Datos que fluyen |
|---|---|---|
| BambooHR | API REST (full access) | Lectura, escritura y reportes de data de empleados |
| Google Workspace | OAuth | Autenticacion de usuarios GLM |
| WhatsApp / Google Chat | API | Instrucciones entrantes y respuestas salientes |
| Supabase / Google Sheets | API | Log de auditoria de cambios |

---

## Configuracion y Setup

### Prerequisitos

- [ ] API key de BambooHR configurada (plan con full access confirmado)
- [ ] Canal de chat definido y configurado (WhatsApp o Google Chat — pendiente decision de Luis Matos)
- [ ] Sistema de autenticacion configurado (pendiente definicion de IT)
- [ ] Variable de entorno BAMBOOHR_API_KEY configurada
- [ ] Variable de entorno BAMBOOHR_SUBDOMAIN configurada
- [ ] Almacenamiento del log de auditoria configurado (pendiente Supabase o Google Sheets)

### Variables de entorno

| Variable | Descripcion | Donde se obtiene |
|---|---|---|
| BAMBOOHR_API_KEY | API Key de BambooHR | BambooHR -> Admin -> API Keys |
| BAMBOOHR_SUBDOMAIN | Subdominio de la cuenta GLM en BambooHR | URL de BambooHR (ej. glm.bamboohr.com) |
| CHAT_CHANNEL | Canal de chat activo (whatsapp / google_chat) | A definir por Luis Matos |
| AUTH_SECRET | Secret del sistema de autenticacion | A definir por IT |
| LOG_STORAGE_URL | URL del almacenamiento del log | Supabase o Google Sheets — a definir |
| ADMIN_USER_ID | ID del usuario con acceso a settings (Maximo Gomez) | A definir al configurar autenticacion |

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/bamboohr-agent

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
# Editar .env con las credenciales reales

# Correr en local
python main.py
```

---

## Como funciona

### Flujo paso a paso

1. Trigger: El usuario envia un mensaje de texto al canal de chat definido (WhatsApp o Google Chat)
2. Autenticacion: El sistema valida la identidad del usuario y sus permisos antes de procesar la instruccion
3. Interpretacion: El agente (Claude o Gemini) analiza el mensaje y determina el modo de operacion — accion, consulta o reporte
4. Ejecucion:
   - Modo accion: Llama a los endpoints correspondientes de BambooHR API para ejecutar el cambio. Si la accion es destructiva (ej. desvincular empleado), el agente pide confirmacion antes de ejecutar
   - Modo consulta: Consulta BambooHR API, extrae la data solicitada y la formatea en lenguaje natural
   - Modo reporte: Genera el reporte solicitado (estandar o personalizado) a partir de la data de BambooHR
5. Log: Cada operacion se registra automaticamente en el log de auditoria con usuario, accion, empleado afectado y timestamp
6. Confirmacion: El agente responde al usuario en el chat con el resultado de la operacion

### Triggers

| Trigger | Frecuencia | Descripcion |
|---|---|---|
| Mensaje entrante en canal de chat | On demand | Usuario envia instruccion o consulta en lenguaje natural |

---

## Testing

### Como probar el sistema

```bash
# Test unitario
python -m pytest tests/

# Test de integracion con BambooHR API
python tests/integration_test.py

# Test manual del agente
# Enviar mensaje de prueba al canal de chat configurado
```

### Casos de prueba minimos

| Caso | Input | Output esperado | Estado |
|---|---|---|---|
| Editar salario | "Actualiza el salario de [empleado] a $X" | Confirmacion + cambio ejecutado en BambooHR | Pendiente |
| Agregar empleado | "Agrega nuevo empleado [datos]" | Confirmacion + empleado creado en BambooHR | Pendiente |
| Desvincular empleado | "Desvincula a [empleado] desde hoy" | Solicitud de confirmacion + ejecucion tras confirmar | Pendiente |
| Subir archivo | "Sube este contrato al perfil de [empleado]" | Archivo subido al perfil en BambooHR | Pendiente |
| Consulta de data | "Cuantos dias de vacaciones tiene [empleado]?" | Respuesta con dato correcto extraido de BambooHR | Pendiente |
| Reporte estandar | "Dame el headcount por pais" | Reporte generado y entregado en el chat | Pendiente |
| Reporte personalizado | "Lista empleados con salario no actualizado en 6 meses" | Reporte personalizado generado | Pendiente |
| Acceso a settings sin permiso | Usuario no-admin intenta modificar configuracion | Acceso denegado, sin ejecucion | Pendiente |
| Acceso a settings con permiso | Maximo Gomez modifica configuracion | Cambio ejecutado correctamente | Pendiente |
| Log de auditoria | Cualquier accion ejecutada | Entrada registrada en log con todos los campos | Pendiente |

---

## Errores conocidos y troubleshooting

| Error | Causa probable | Solucion |
|---|---|---|
| 401 Unauthorized en BambooHR | API Key vencida o incorrecta | Renovar key en BambooHR -> Admin -> API Keys y actualizar .env |
| Acceso denegado a settings | Usuario no tiene permisos de admin | Verificar ADMIN_USER_ID en variables de entorno |
| Agente no interpreta la instruccion | Instruccion muy ambigua o incompleta | El agente debe solicitar aclaracion al usuario antes de ejecutar |
| Log no registra la accion | Conexion con almacenamiento del log fallida | Verificar LOG_STORAGE_URL y credenciales de acceso |
| Canal de chat no recibe mensajes | Webhook no configurado correctamente | Revisar configuracion del canal en la plataforma correspondiente |

---

## Monitoreo

### Como saber si el sistema esta funcionando

- Log de auditoria: Revisar que las acciones ejecutadas esten siendo registradas correctamente
- Canal de chat: Enviar un mensaje de prueba y verificar que el agente responda
- BambooHR: Verificar aleatoriamente que los cambios ejecutados por el agente se reflejen correctamente
- Alertas: A definir por IT — el sistema debe enviar alerta a Luis Matos si falla una ejecucion critica

---

## Estructura del repositorio

```
/bamboohr-agent
├── README.md                  <- Este archivo
├── .env.example               <- Variables de entorno de ejemplo (sin valores reales)
├── main.py                    <- Punto de entrada principal
├── /src
│   ├── agent.py               <- Logica del agente — interpretacion de instrucciones
│   ├── bamboohr_client.py     <- Integracion con BambooHR API
│   ├── auth.py                <- Sistema de autenticacion y permisos
│   ├── audit_log.py           <- Registro de auditoria
│   └── chat_interface.py      <- Integracion con canal de chat
├── /tests
│   ├── test_agent.py          <- Tests del agente
│   ├── test_bamboohr.py       <- Tests de integracion con BambooHR API
│   └── integration_test.py    <- Tests de integracion completos
├── /docs
│   └── architecture.png       <- Diagrama de arquitectura (pendiente)
├── CHANGELOG.md               <- Historial de cambios
└── DECISIONS.md               <- Log de decisiones tecnicas
```

---

## CHANGELOG

```
[Junio 8, 2026] v0.1 — Inicio del ciclo. Repo creado.
```

---

## DECISIONS LOG

### DEC-001 — Canal de chat

* Fecha: Junio 2026
* Contexto: El agente necesita un canal de comunicación para recibir instrucciones y responder al equipo de RRHH. GLM opera dentro de Google Workspace y el proyecto manejará acciones sensibles sobre información de empleados en BambooHR.
* Opciones consideradas: WhatsApp API vs Google Chat API
* Decisión: Usar Google Chat como canal principal para la primera versión del BambooHR Agent.
* Razón: Google Chat permite trabajar con identidad corporativa de Google Workspace, usuarios internos, mejor trazabilidad y menor riesgo de suplantación que WhatsApp para acciones sensibles de RRHH.
* Impacto: WhatsApp queda como posible canal futuro para notificaciones, recordatorios, alertas o consultas simples de bajo riesgo, pero no como canal principal para ejecutar acciones críticas en BambooHR.

### DEC-002 — Sistema de autenticación

* Fecha: Junio 2026
* Contexto: Se necesita validar la identidad de cada usuario antes de permitir consultas, modificaciones, reportes o acciones sobre BambooHR.
* Opciones consideradas: Google Workspace / OAuth vs sistema propio de usuarios vs autenticación por número de WhatsApp
* Decisión: Usar Google Workspace como proveedor de identidad.
* Razón: Evita crear usuarios y contraseñas propias, aprovecha las cuentas corporativas existentes y permite auditar cada solicitud por correo corporativo.
* Impacto: Solo usuarios corporativos autorizados podrán interactuar con el agente. Antes de procesar cualquier instrucción, el sistema deberá validar identidad, rol y permisos del usuario.

### DEC-003 — Modelo de autorización y permisos

* Fecha: Junio 2026
* Contexto: No basta con saber que el usuario pertenece a GLM. El agente debe validar que el usuario tenga permiso para ejecutar una acción específica según rol, país/área permitida, sensibilidad del dato y nivel de riesgo de la operación.
* Opciones consideradas: Google Sheets vs Supabase/Postgres vs Neo4j
* Decisión: Usar Neo4j como grafo de autorización y relaciones.
* Razón: Neo4j permite modelar relaciones complejas entre usuarios, roles, países, áreas, acciones, campos sensibles, confirmaciones y aprobaciones.
* Impacto: Neo4j guardará metadata de permisos y relaciones. No almacenará salarios reales, documentos, datos personales sensibles completos ni historial completo de BambooHR.

### DEC-004 — Almacenamiento del log de auditoría

* Fecha: Junio 2026
* Contexto: Cada acción relevante debe quedar registrada con usuario, acción, empleado afectado si aplica, timestamp, resultado de autorización y resultado de ejecución.
* Opciones consideradas: Supabase/Postgres vs Google Sheets
* Decisión: Usar Supabase/Postgres como almacenamiento principal del log de auditoría.
* Razón: Supabase/Postgres ofrece mayor control, estructura, trazabilidad, seguridad y escalabilidad que Google Sheets para un proyecto con datos sensibles de RRHH.
* Impacto: Google Sheets podrá usarse solo como herramienta auxiliar de visualización o exporte, pero no como log principal de auditoría.

### DEC-005 — Separación de responsabilidades entre n8n y Python Service

* Fecha: Junio 2026
* Contexto: n8n es ideal para orquestar flujos, recibir mensajes, llamar servicios externos y responder al usuario. Sin embargo, las reglas críticas de permisos, autorización, ejecución contra BambooHR y auditoría deben mantenerse centralizadas, versionadas y auditables.
* Opciones consideradas: Hacer toda la lógica en n8n vs separar la lógica crítica en un Python Service
* Decisión: Usar n8n como orquestador del flujo y un Python Service como capa de lógica crítica.
* Razón: Separar la lógica crítica evita que reglas sensibles de RRHH queden dispersas en múltiples nodos visuales. El Python Service permite validar permisos, consultar Neo4j, ejecutar BambooHR API y registrar auditoría de forma más controlada y fácil de probar.
* Impacto: n8n recibirá el mensaje, coordinará el flujo y responderá al usuario. El Python Service validará permisos, consultará Neo4j, ejecutará acciones autorizadas en BambooHR API y registrará auditoría en Supabase/Postgres.

### DEC-006 — Política de seguridad para acciones sensibles

* Fecha: Junio 2026
* Contexto: El agente podrá ejecutar acciones que impactan datos sensibles de empleados, nómina y procesos de RRHH. Una instrucción mal interpretada no debe ejecutarse automáticamente si representa riesgo alto.
* Opciones consideradas: Ejecutar acciones directamente vs solicitar confirmación/aprobación según riesgo
* Decisión: Requerir confirmación explícita para acciones sensibles y aprobación cuando aplique según política interna.
* Razón: Cambios de salario, desvinculaciones, creación de empleados, cambios de manager, cambios de fechas críticas y acciones que impacten nómina requieren control adicional antes de ejecutarse.
* Impacto: Las acciones sensibles no se ejecutarán directamente después de ser interpretadas. El agente deberá pedir confirmación y registrar la operación en auditoría. Los settings de BambooHR quedan bloqueados para todos excepto Máximo Gómez.

---

## Contactos del proyecto

| Rol | Nombre | Contacto |
|---|---|---|
| Product Owner | Maximo Gomez | [completar] |
| IT Manager | Luis Matos | [completar] |
| Developer | Isaac Aracena | [completar] |

---

## Definition of Done

- [ ] Agente ejecuta los 3 modos: accion, consulta y reporte
- [ ] 95% de acciones ejecutadas correctamente en pruebas reales
- [ ] Tiempo por operacion menor a 30 segundos
- [ ] Sistema de permisos funcionando — settings bloqueados para no-admins
- [ ] Log de auditoria registrando todas las operaciones
- [ ] Todos los casos de prueba en estado OK
- [ ] Codigo commiteado y pusheado a Gitea
- [ ] README completo y actualizado
- [ ] Variables de entorno documentadas en .env.example
- [ ] Probado en ambiente real con equipo de RRHH
- [ ] Luis Matos valido el output
- [ ] Maximo aprobo el resultado final

---

Documento mantenido por el equipo GLM IT - Ultima actualizacion: Junio 8, 2026