Rebuscada

Joc de paraules en català on heu d'endevinar una paraula objectiu provant paraules i veient com de properes estan en un rànquing de similitud semàntica. Inspirat en Semantle / Contexto.

Web: rebuscada.cat

Requisits previs

• Python 3.10+
• Node.js 18+ (per al frontend)
• Model FastText per al català (cc.ca.300.bin, ~7 GB) — només si voleu generar rànquings nous. Es descarrega automàticament.

Instal·lació

# 1. Clonar el repositori
git clone <url-del-repositori>
cd rebuscada

# 2. Instal·lar dependències de Python
pip install -r requirements.txt

# 3. Instal·lar dependències del frontend
cd frontend && npm install && cd ..

# 4. Configurar variables d'entorn
cp .env.example .env
# Editar .env segons les vostres necessitats

# 5. (Opcional) Instal·lar eines de desenvolupament
pip install pytest pytest-asyncio httpx ruff

Posada en marxa

Servidor de joc (API)

python server.py
# Escolta a http://localhost:8000/

Servidor d'administració

python server_admin.py
# Escolta a http://localhost:5001/
# Panell web a http://localhost:5001/admin/

Frontend (desenvolupament)

cd frontend
npm start
# Escolta a http://localhost:3000/

Tot alhora (amb Make)

make serve     # Servidor de joc
make admin     # Servidor d'administració
make frontend  # Frontend de desenvolupament

Tests

# Tests del backend (Python)
pytest tests/ -v

# Tests del frontend (Jest)
cd frontend && npm test

# Tots els tests
make test

# Linting del backend
ruff check .
make lint

Estructura del projecte

rebuscada/
├── server.py              # API del joc (FastAPI) — endpoints: /guess, /pista, /ranking...
├── server_admin.py        # API d'administració — gestió de rànquings, calendari, estadístiques
├── stats.py               # Estadístiques de joc (SQLite)
├── diccionari.py          # Diccionari reduït amb freqüències
├── diccionari_full.py     # Diccionari complet (SQLite) per a validació detallada
├── generate.py            # Generació de rànquings (FastText/OpenAI/SOTA)
├── generateLLM.py         # Generació de paraules amb LLM
├── proximitat.py          # Similitud semàntica amb FastText
├── proximitatOpenAI.py    # Similitud amb embeddings OpenAI
├── proximitatSOTA.py      # Similitud amb Sentence Transformers
├── fast_ai.py             # Interfície multi-backend per LLM
│
├── frontend/              # Aplicació React (TypeScript)
│   ├── src/
│   │   ├── App.tsx        # Component principal del joc
│   │   └── gameUtils.ts   # Utilitats (numerals romans, estat del joc)
│   └── package.json
│
├── admin/                 # Panell d'administració (HTML/JS/CSS vanilla)
│   ├── index.html
│   ├── admin.js
│   └── admin.css
│
├── scripts/               # Scripts de manteniment
│   ├── build_definitions.py    # Construir definicions des del Wiktionary
│   ├── update_rankings.py      # Actualitzar rànquings amb el diccionari actual
│   ├── import_log_stats.py     # Importar estadístiques des de game.log
│   └── ...
│
├── tests/                 # Tests del backend (pytest)
├── data/                  # Dades del joc (no versionades)
│   ├── words/             # Rànquings per paraula (paraula → posició)
│   ├── games.json         # Calendari de jocs
│   ├── diccionari.json    # Diccionari reduït
│   └── stats.db           # Base de dades d'estadístiques
│
├── AGENTS.md              # Directrius del projecte per a agents IA
├── CONTRIBUTING.md        # Guia per contribuir
├── pyproject.toml         # Configuració Python (pytest, ruff)
├── requirements.txt       # Dependències Python
└── Makefile               # Comandes de desenvolupament

Com funciona el joc

1. Cada dia es publica una paraula objectiu segons el calendari (data/games.json).
2. El jugador escriu paraules per intentar endevinar-la.
3. Per a cada paraula, el servidor retorna la seva posició dins un rànquing de similitud semàntica (posició 0 = la paraula objectiu).
4. El jugador pot demanar pistes (paraules properes al rànquing) o rendir-se.
5. Hi ha mode competició per jugar amb altres persones en temps real (WebSocket).

Generació de rànquings

Per generar nous rànquings de paraules (requereix el model FastText):

# Generar rànquing per una paraula
python generate.py --paraula "casa" --algorisme fasttext

# Generar 10 paraules aleatòries
python generate.py --random 10 --algorisme fasttext

# Amb filtre creuat (FastText + OpenAI)
python generate.py --paraula "gat" --filtre-creuat --algorisme fasttext

Variables d'entorn

Variable	Per defecte	Descripció
PORT	8000	Port del servidor de joc
ADMIN_PORT	5001	Port del servidor d'administració
ADMIN_PASSWORD	(buit)	Contrasenya d'admin (buit = obert)
ADMIN_SHARED_SECRET	(buit)	Secret per comunicació entre servidors
DICCIONARI_PATH	data/diccionari.json	Ruta al diccionari
DEFAULT_REBUSCADA	paraula	Paraula per defecte
ALLOWED_ORIGINS	localhost:3000,rebuscada.cat	Orígens CORS
RANKING_CACHE_SIZE	10	Mida del cache de rànquings
STATS_DB_PATH	data/stats.db	Ruta de la BD d'estadístiques
OPENAI_API_KEY	—	Clau API d'OpenAI (per embeddings)
CHATANYWHERE_API_KEY	—	Clau API alternativa per LLM
GEMINI_API_KEY	—	Clau API de Google Gemini
AI_API	—	Backend d'IA (openai, chatanywhere, gemini)