Laucha1312
245 lines
8.3 KiB
Markdown
245 lines
8.3 KiB
Markdown
# OnAPB Genius Agent — Spec de Diseño
|
||
|
||
**Fecha:** 2026-04-09
|
||
**Rama:** `feature/genius-agent`
|
||
**Stack:** Laravel 12, Prism PHP (prism-php/prism), Google Gemini 1.5 Flash, MySQL, Alpine.js
|
||
|
||
---
|
||
|
||
## 1. Objetivo
|
||
|
||
Implementar un agente de IA conversacional ("OnAPB Genius") integrado en onapb.com con dos modos de operación según el rol del usuario:
|
||
|
||
- **Público** (no logueado, aficionado, jugador): asistente de navegación y consultas usando el `MANUAL_USUARIO.md` como contexto RAG simplificado. Sin tools. Sin persistencia entre sesiones.
|
||
- **Admin** (SuperAdmin rol=1 / GeneralAdmin rol=2): automatización de tareas mediante function calling (Tools). Historial persistente en MySQL, auto-purgado a los 30 días.
|
||
|
||
---
|
||
|
||
## 2. Decisiones de Arquitectura
|
||
|
||
| Decisión | Elección | Razón |
|
||
|---|---|---|
|
||
| SDK de AI | `prism-php/prism` | Soporte probado de Gemini 1.5 Flash + tools. Más estable que `laravel/ai` (nuevo). |
|
||
| Modelo | `gemini-1.5-flash` | Velocidad (2–5s), costo bajo, function calling. |
|
||
| Streaming | No — JSON completo | Hosting compartido Hostinger con límites PHP desconocidos. Evita problemas de output buffer. |
|
||
| Memoria admin | MySQL (`agent_threads`) | Sin Redis. JSON column para mensajes. Purge automático 30 días. |
|
||
| Memoria público | Session PHP | Stateless entre sesiones. Simple, sin overhead de BD. |
|
||
| Tools | Solo si admin_logged_in | Validado en `GeniusAgentService`, no en Gemini. |
|
||
|
||
---
|
||
|
||
## 3. Estructura de Archivos
|
||
|
||
```
|
||
app/
|
||
├── AI/
|
||
│ ├── Tools/
|
||
│ │ ├── CrearPartidoTool.php
|
||
│ │ ├── CargarPuntajeTool.php
|
||
│ │ ├── RedactarNoticiaTool.php
|
||
│ │ ├── ListarEquiposTool.php
|
||
│ │ └── ListarEventosTool.php
|
||
│ └── Prompts/
|
||
│ ├── SystemPromptAdmin.php
|
||
│ └── SystemPromptPublic.php
|
||
├── Services/
|
||
│ └── GeniusAgentService.php
|
||
├── Http/Controllers/
|
||
│ └── GeniusAgentController.php
|
||
├── Models/
|
||
│ └── AgentThread.php
|
||
└── Console/Commands/
|
||
└── PurgeAgentThreads.php
|
||
|
||
database/migrations/
|
||
└── xxxx_create_agent_threads_table.php
|
||
|
||
resources/views/components/
|
||
└── genius-chat.blade.php
|
||
|
||
routes/web.php
|
||
└── POST /agent/chat (throttle: 20/min por IP)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Schema de Base de Datos
|
||
|
||
```sql
|
||
CREATE TABLE agent_threads (
|
||
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
|
||
thread_id VARCHAR(36) NOT NULL UNIQUE, -- UUID generado en frontend
|
||
admin_id INT NOT NULL, -- session('admin_id')
|
||
messages JSON NOT NULL, -- array [{role, content}]
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
expires_at TIMESTAMP NOT NULL -- created_at + 30 días
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Tools Disponibles (Admin)
|
||
|
||
Cada tool implementa la interfaz Prism `Tool`. El agent loop permite que Gemini llame la misma tool N veces para operaciones batch (ej. cargar puntajes de todos los partidos de una jornada).
|
||
|
||
| Tool | Parámetros | Acción en BD |
|
||
|---|---|---|
|
||
| `CrearPartidoTool` | `id_equipo_local`, `id_equipo_visitante`, `fecha_evento`, `hora_inicio`, `hora_fin`, `sede`, `id_torneo` | `Evento::create(...)` |
|
||
| `CargarPuntajeTool` | `id_evento`, `marcador_local`, `marcador_visitante` | `Evento::find()->update(...)` |
|
||
| `RedactarNoticiaTool` | `titulo`, `contenido`, `id_torneo?`, `categoria?` | `Noticia::create(...)` |
|
||
| `ListarEquiposTool` | `id_torneo?`, `id_club?`, `grupo?` | `Equipo::query()` con join a pivot `torneo_equipo` filtrando por `grupo` (solo lectura) |
|
||
| `ListarEventosTool` | `fecha_desde?`, `fecha_hasta?`, `id_torneo?` | `Evento::query()->get()` (solo lectura) |
|
||
|
||
**Nota sobre `grupo`:** No es un modelo separado. Es una columna en la tabla pivot `torneo_equipo` (relación `Torneo::equipos()->withPivot('grupo')`). `ListarEquiposTool` filtra con `wherePivot('grupo', $grupo)`.
|
||
|
||
**Agregar una nueva tool en el futuro:**
|
||
1. Crear `app/AI/Tools/NuevaTool.php`
|
||
2. Registrarla en `GeniusAgentService::getAdminTools()`
|
||
|
||
---
|
||
|
||
## 6. Flujo de Datos
|
||
|
||
### Usuario público
|
||
```
|
||
POST /agent/chat { message }
|
||
→ session()->get('agent_messages', [])
|
||
→ GeniusAgentService::chatPublic(message, history)
|
||
→ System prompt: navegación + MANUAL_USUARIO.md completo como contexto (el archivo es pequeño; si crece >50KB usar solo las primeras 200 líneas)
|
||
→ Prism → Gemini (sin tools)
|
||
→ Respuesta de texto
|
||
→ session()->put('agent_messages', [...])
|
||
→ return JSON { reply }
|
||
```
|
||
|
||
### Admin
|
||
```
|
||
POST /agent/chat { message, thread_id? }
|
||
→ AgentThread::findOrCreate(thread_id, admin_id)
|
||
→ GeniusAgentService::chatAdmin(message, thread)
|
||
→ System prompt: automatización de tareas OnAPB
|
||
→ Prism → Gemini con tools
|
||
→ [si Gemini llama tool] → Tool::handle() → resultado
|
||
→ [Gemini puede llamar N tools] → agent loop
|
||
→ Respuesta final de texto
|
||
→ thread->appendMessages([...])
|
||
→ thread->save()
|
||
→ return JSON { reply, thread_id }
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Seguridad
|
||
|
||
- **Tools bloqueadas a no-admins:** `GeniusAgentService` valida `session('admin_logged_in')` antes de incluir tools.
|
||
- **Rate limiting:** `throttle:20,1` en la ruta `/agent/chat`.
|
||
- **Validación de input:** `message` requerido, string, máx. 1000 caracteres.
|
||
- **Aislamiento de threads:** cada thread valida `admin_id = session('admin_id')`. No hay acceso cruzado entre admins.
|
||
- **API key:** solo en `.env` (`GEMINI_API_KEY`). Nunca en código ni en BD.
|
||
|
||
---
|
||
|
||
## 8. Manejo de Errores
|
||
|
||
| Caso | Comportamiento |
|
||
|---|---|
|
||
| Gemini timeout / 5xx | `catch RequestException` → JSON `{ error: "El agente no responde, reintentá en un momento." }` |
|
||
| Tool falla (ej. evento no existe) | Tool retorna `{ error: "..." }` → Gemini lo incorpora en su respuesta |
|
||
| Thread expirado / no encontrado | Se crea un nuevo thread automáticamente |
|
||
| API key inválida / quota excedida | Log en Laravel + respuesta genérica (sin exponer detalles de la API) |
|
||
| Timeout de Hostinger | `set_time_limit(120)` al inicio del controller action |
|
||
|
||
---
|
||
|
||
## 9. Purge de Threads
|
||
|
||
Comando `php artisan agent:purge-threads` que elimina `agent_threads` donde `expires_at < NOW()`.
|
||
|
||
**Schedule:** Se registra en `routes/console.php` para ejecutarse diariamente. En Hostinger sin queue worker, se puede configurar como cron en hPanel:
|
||
|
||
```
|
||
# Reemplazar /home/TU_USUARIO/public_html con la ruta real de tu cuenta Hostinger
|
||
0 3 * * * cd /home/TU_USUARIO/public_html && php artisan agent:purge-threads >> /dev/null 2>&1
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Frontend — Chat Bubble
|
||
|
||
Componente Blade `genius-chat.blade.php` incluido al final de `resources/views/layouts/app.blade.php`:
|
||
|
||
- Botón flotante (bottom-right) con ícono de chat
|
||
- Panel slide-up con historial de mensajes de la sesión actual
|
||
- Alpine.js para estado local (open/closed, messages, loading spinner)
|
||
- Tailwind para estilos (sin dependencias adicionales)
|
||
- Rol-aware: el frontend no diferencia, la diferencia la hace el backend
|
||
|
||
---
|
||
|
||
## 11. Comandos de Deploy
|
||
|
||
### Instalación inicial (local y producción)
|
||
|
||
```bash
|
||
# 1. Instalar Prism PHP
|
||
composer require prism-php/prism
|
||
|
||
# 2. Publicar config de Prism (opcional)
|
||
php artisan vendor:publish --provider="EchoLabs\Prism\PrismServiceProvider"
|
||
|
||
# 3. Agregar en .env
|
||
GEMINI_API_KEY=tu_api_key_aqui
|
||
|
||
# 4. Ejecutar migration de agent_threads
|
||
php artisan migrate
|
||
|
||
# 5. Registrar el comando de purge (se hace automáticamente con el código)
|
||
# Verificar que está en routes/console.php
|
||
|
||
# 6. Limpiar cachés después del deploy
|
||
php artisan config:clear
|
||
php artisan cache:clear
|
||
php artisan view:clear
|
||
php artisan route:clear
|
||
|
||
# 7. Re-cachear para producción
|
||
php artisan config:cache
|
||
php artisan route:cache
|
||
php artisan view:cache
|
||
```
|
||
|
||
### Comandos de mantenimiento
|
||
|
||
```bash
|
||
# Purge manual de threads expirados
|
||
php artisan agent:purge-threads
|
||
|
||
# Ver logs del agente
|
||
php artisan pail --filter="GeniusAgent"
|
||
|
||
# Limpiar todos los threads (emergencia)
|
||
php artisan tinker --execute="App\Models\AgentThread::truncate();"
|
||
```
|
||
|
||
### Deploy en Hostinger (via SSH o File Manager)
|
||
|
||
```bash
|
||
# Subir archivos nuevos y correr:
|
||
php artisan migrate --force
|
||
php artisan config:cache
|
||
php artisan route:cache
|
||
php artisan view:cache
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Configuración `.env` requerida
|
||
|
||
```env
|
||
GEMINI_API_KEY=tu_api_key_de_google_ai_studio
|
||
|
||
# Opcional: ajustar timeout HTTP de Prism
|
||
PRISM_HTTP_TIMEOUT=30
|
||
```
|