osu! Standard Recommender - Backend

FastAPI backend para recomendaciones de beatmaps de osu! standard. Usa cosine similarity basado en el perfil del jugador.

Quick Start

# Instalar
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Configurar
cp .env.example .env
# Edita .env con tus credenciales de osu! API

# Correr
uvicorn app.main:app --reload

Configuración

Variables obligatorias en .env:

OSU_CLIENT_ID=tu_id
OSU_CLIENT_SECRET=tu_secret
OSU_REDIRECT_URI=http://localhost:8000/auth/callback
SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

Variables opcionales (ver app/config.py para defaults).

API Endpoints

Auth

• GET /auth/login - Inicia OAuth con osu!
• GET /auth/callback - Callback de OAuth
• POST /auth/logout - Cierra sesión
• GET /auth/me - Usuario actual (session data)

User

• GET /api/user/profile - Perfil del usuario con stats
• GET /api/user/recent - Últimos scores (cache: 2 min)
• POST /api/user/recent/refresh - Forzar actualización de scores

Recomendaciones

• GET /recommendations?mods=all&limit=10 - Beatmaps recomendados
  • Query params: mods (all, NM, HD, DT, HR), sr_min, sr_max, limit (max 50)
• GET /recommendations/latest - Último batch de recomendaciones guardadas
• GET /recommendations/saved - Todas las recomendaciones guardadas (hasta 20)
• GET /recommendations/collaborative - Recomendaciones por filtrado colaborativo

Análisis

• GET /improvement?limit=50 - Análisis de progreso basado en scores recientes
• GET /improvement/comparisons - Comparaciones de scores repetidos

Health

• GET /health - Estado del servidor

Tests

pytest

Producción

SESSION_HTTPS_ONLY=True  # Obligatorio
uvicorn app.main:app --workers 4 # Ajustar según tu CPU

Arquitectura

• Hexagonal: domain/ → ports/ → adapters/ → api/
• Caché: En memoria con TTL (5min usuarios, 10min top plays, 1h beatmaps, 2min recent scores)
• Rate limiting: 1000 req/min global, 120 req/min por usuario
• DB: SQLite async

Algoritmo

1. Extrae features de tus top plays (SR, BPM, length, AR, CS)
2. Calcula similitud coseno con beatmaps candidatos
3. Ajusta SR según mods (DT: 1.35x, HD: 1.07x, HR: 1.06x)
4. Genera razones en español
5. Excluye ya jugados (últimas 20)

Stack

• Python 3.11+, FastAPI, SQLAlchemy 2.0
• SQLite + aiosqlite
• httpx async
• numpy, scipy