# 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 (WhatsApp vs Google Chat)
- Fecha: Pendiente — Semana 1
- Contexto: El agente necesita un canal de comunicacion. GLM opera en Google Workspace pero Maximo usa WhatsApp para operaciones similares
- Opciones consideradas: WhatsApp API vs Google Chat API
- Decision: A definir por Luis Matos en Semana 1
- Razon: Pendiente

### DEC-002 — Sistema de autenticacion
- Fecha: Pendiente — Semana 1
- Contexto: Se necesita validar la identidad de cada usuario para aplicar permisos correctamente
- Opciones consideradas: Google OAuth vs sistema propio vs otro
- Decision: A definir por IT en Semana 1
- Razon: Pendiente

### DEC-003 — Almacenamiento del log de auditoria
- Fecha: Pendiente — Semana 1
- Contexto: Cada accion ejecutada debe quedar registrada con usuario, accion, timestamp y resultado
- Opciones consideradas: Supabase / Postgres vs Google Sheets
- Decision: A definir por IT en Semana 1
- Razon: Pendiente

---

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