Wiki

BogaBot es un bot de Discord modular. El módulo 1 (el MVP actual) es el ranking de League of Legends de un grupo de amigos: vincular cuenta de Riot → ingerir partidas desde la Riot API 1×/día → calcular un puntaje configurable por jugador → publicar rankings en Discord.

Está armado por capas reemplazables: el storage vive detrás de una interfaz (hoy es “Discord como base de datos”, migrar a SQLite o Postgres es una clase nueva), los módulos son cogs autocontenidos y la fórmula del ranking es un archivo YAML editable sin tocar código.

Si el bot ya está en tu server, lo único que tenés que hacer es vincularte:

1. Corré /link Nombre#TAG con tu Riot ID completo (el nombre y el tag que ves en el cliente de LoL, ej. Faker#KR1).
2. El bot valida la cuenta contra la Riot API. Si existe, queda vinculada y tus partidas de esta semana empiezan a contar.
3. Usá /ranking cuando quieras ver la tabla, o esperá el posteo automático de cada noche.

Setup en Windows / PowerShell: python -m venv venv → venv\Scripts\activate → pip install -r requirements.txt.

Permisos al invitarlo

En OAuth2 → URL Generator, scopes bot y applications.commands. Bot permissions:

• Send Messages, Embed Links, View Channel y Read Message History en los canales de storage y de rankings.
• Manage Roles solo si vas a usar LOL_ROLE_ID (para que el bot asigne ese rol al vincular).
• No requiere intents privilegiados: dejalos apagados.

Con el modo desarrollador activado (Ajustes → Avanzado), click derecho sobre cada canal o rol te deja copiar su ID. Necesitás también el ID del server para DISCORD_GUILD_ID.

En developer.riotgames.com generás la key. Va en RIOT_API_KEY.

Ajustá también RIOT_PLATFORM y RIOT_REGION a tu región. Por defecto está en LAS: RIOT_PLATFORM=la2, RIOT_REGION=americas (LAS, LAN y NA rutean a americas).

Todo sale de un archivo .env — el código nunca hardcodea secretos ni IDs. Ninguno de los .env.* reales se commitea.

El ambiente lo elige la variable de shell BOGABOT_ENV (se setea en la terminal antes de correr, no dentro del .env):

# local, default staging
python run.py

# explícito
$env:BOGABOT_ENV = "production"
python run.py

# con el script (consola + log en logs\)
.\scripts\run_bot.ps1 -Environment production

El default es staging a propósito: si te olvidás de setear la variable, nunca corrés contra producción por accidente. Recomendado: staging apunta a otro bot y otro server, no al mismo, porque el storage vive en canales de Discord y mezclarías datos de prueba con datos reales.

/ingest-now es idempotente: el dedup por (match_id, puuid) saltea lo que ya está guardado, así que correrlo de más no duplica nada.

1. Cada partida se guarda como un registro por jugador, pero solo si la jugaste acompañado de al menos otro vinculado del grupo. Las solitarias se descartan en la ingesta (se chequea metadata.participants del JSON de match-v5).
2. Se excluyen los remakes (menos de 5 min o early surrender).
3. Las ventanas son día y semana desde el lunes 00:00 hora local (TIMEZONE, default Buenos Aires).
4. En cada ventana se agregan las stats por jugador y el motor de scoring aplica la fórmula de config/scoring.yaml.
5. El job diario corre a DAILY_POST_HOUR:DAILY_POST_MINUTE (recomendado 23:55): ingesta → ranking del día. Los lunes, además, el recap semanal “Trolls y Pros” de la semana que cerró — contando solo Ranked Flex (queue 440), para medir el juego serio del grupo.
6. Dedup por (match_id, puuid)sin cursor: cada corrida pide “desde el lunes” y saltea lo ya guardado.

La fórmula vive en config/scoring.yaml y se edita sin tocar código. Para cada jugador se calcula cada métrica (promediada por partida), se normaliza entre todos los jugadores y el puntaje final es la suma de peso × valor_normalizado.

Métricas activas por defecto

↓ = menos es mejor (el valor normalizado se invierte). El motor soporta además avg_kills, avg_assists, cs_per_min, desactivadas por defecto — se activan agregándolas al YAML.

Partida terminada

Si MATCH_NOTIFY_CHANNEL_ID está seteado, cada MATCH_POLL_INTERVAL_MINUTES (5 por defecto) el bot chequea partidas nuevas y, por cada una jugada con otro vinculado, postea un mensaje etiquetando a los jugadores del grupo que la jugaron — con el resultado de cada uno, por si terminaron en equipos contrarios.

Trolleadas y papelones

Cada corrida del scheduler detecta, entre las últimas 48 h, partidas trolleadas (KDA < 0.5 y FF antes de los 20 min) y papelones (derrota antes de los 25 min). Las trolls avisan en RANKING_CHANNEL_ID; los papelones en GENERAL_CHANNEL_ID. Hay un ranking histórico de trolls, y el aviso consulta el timeline de la partida para mostrar en qué minuto moriste por primera vez.

Logs a Discord

Si LOG_CHANNEL_ID está seteado, los logs de nivel LOG_CHANNEL_LEVEL (WARNING por defecto) o superior se reenvían también a ese canal, además de la consola. Pensado para enterarte de errores (Riot caído, key vencida) sin mirar la terminal.

Local

python run.py directo, o .\scripts\run_bot.ps1 [-Environment production], que abre consola visible y espeja todo a logs\<ambiente>\. No levantes dos instancias contra el mismo ambiente/server: te responderían los comandos dos veces.

VPS (systemd)

El repo trae deploy/bogabot.service. El setup es una vez: clonar, venv + pip install, copiar el .env por scp, instalar el service y systemctl enable --now bogabot. Después, cada push a main que pase los tests se despliega solo por GitHub Actions (git pull + pip install + systemctl restart).

sudo cp deploy/bogabot.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now bogabot
sudo journalctl -u bogabot -f  # logs en vivo

• Alcance: módulo 1 (ranking de LoL). Sin funciones de IA todavía — están en el backlog como cog aparte.
• Storage: hoy es Discord (mensajes JSON en un canal privado + índice en memoria). Es O(n) mensajes; migrar a una DB real es una clase nueva en storage/ y una línea en bot.py.
• Colas:el ranking diario/semanal cuenta todas las colas (incluye ARAM y rotativos); el recap “Trolls y Pros” solo Ranked Flex.
• Región: decisión tomada para LAS (la2 / americas); configurable para otras.

Bugs, ideas y pedidos → issues del repo.