GameLog

Catálogo pessoal de jogos com motor de recomendação semântico e agente de chat com IA. Registra o histórico, acompanha o backlog e recomenda jogos com base no gosto real do usuário — não só por gênero, mas por vibe de gameplay.

---

O que é

App web single-file (index.html) que roda localmente. Sem servidor externo, sem conta em nenhum serviço. Os dados ficam em arquivos JSON no próprio repositório.

Abas principais:

• Catálogo — registro de jogos jogados com nota (1–10), plataforma, tempo de jogo e comentários
• Backlog — 7.034 jogos com busca, filtros e infinite scroll
• Wishlist — fila de espera antes de iniciar um jogo
• Recomendações — motor semântico com embeddings + perfil do usuário
• Game Agent — chat com IA que conversa, entende o que você quer e recomenda jogos personalizados
• Perfil & Stats — afinidade por gênero, horas estimadas, distribuição por plataforma

---

Game Agent

Chat conversacional que age como um sommelier de jogos. Faz 1–2 perguntas pra entender o que você quer e retorna 2–3 recomendações com explicação personalizada por jogo.

Como funciona:

1. Usuário descreve o que quer (ou menciona um jogo de referência)
2. Agente faz perguntas focadas pra entender mood, gênero e estilo
3. Chama search_by_description ou search_games com os sinais coletados
4. A busca semântica blenda a query com o vetor de gosto do usuário (70% gosto + 30% descrição)
5. Retorna 2–3 cards com explicação específica pro perfil

Ferramentas do agente:

Tool	Quando usa	Blend de gosto
search_by_description	Busca por vibe/descrição	70% gosto + 30% descrição
search_games	Usuário cita um jogo específico	50% gosto + 50% referência

Modos:

• Com histórico — usa os jogos avaliados como vetor de gosto; exclui jogos já jogados dos resultados
• Sem histórico — busca pura por descrição; inclui jogos já jogados nos resultados

Stack: Gemini 3.1 Flash Lite (500 RPD gratuitos) + HuggingFace BAAI/bge-large-en-v1.5 via proxy local para embeddings semânticos, com fallback por vetor de âncora quando HF não está disponível.

---

Motor de recomendação (aba ML)

Pipeline de dados

IGDB API ──► backlog_meta.json ─────────────────────────────┐
SteamSpy ──► steam_tags.json   ──► enrich_groq_multi.py ──► enriched_descriptions.json
Wikipedia ──► (fetch_wiki_single.py) ───────────────────────┘
                                            │
                                            ▼
                                  generate_embeddings.py
                                  (Google Colab T4 recomendado)
                                            │
                                            ▼
                                      embeddings.bin
                                            │
                                            ▼
                                       index.html
                               (cosine similarity no browser)

Scorer final

Sinal	Peso padrão	Descrição
semantic_similarity	ajustável	Cosseno entre vetor da query e vetor do jogo
igdb_score	ajustável	Bayesian weighted (prior C=100, m=75)

Pesos configuráveis via sliders na aba ML. Modos:

• Balanceado — pesos padrão
• Hidden Gems — penaliza popularidade
• Top Rated — filtra jogos com poucos reviews

---

Estrutura do repositório

jogos/
├── index.html                  ← app completo (HTML/CSS/JS, ~3600 linhas)
├── server.py                   ← servidor local na porta 7432
├── backlog.json                ← catálogo de 7.034 jogos
├── games.json                  ← dados do usuário (histórico, notas, perfil)
├── embeddings.bin              ← vetores float32, 1024 dims por jogo (~28MB, gitignored)
├── .env.example                ← template de variáveis de ambiente
│
├── data/                       ← arquivos de pipeline (gitignored, pesados)
│   ├── backlog_meta.json       ← metadata IGDB (~15MB)
│   ├── steam_tags.json         ← tags Steam por jogo (~1.6MB)
│   ├── enriched_descriptions.json  ← descrições LLM por jogo (~3MB)
│   └── backlog_full.json       ← catálogo original completo (13.587 jogos)
│
├── scripts/                    ← pipeline de dados
│   ├── fetch_meta.py           ← busca metadata do IGDB
│   ├── fetch_steam_tags.py     ← busca tags do SteamSpy
│   ├── fetch_wiki_single.py    ← busca resumos da Wikipedia
│   ├── enrich_groq_multi.py    ← gera descrições LLM (Groq, multi-modelo)
│   ├── generate_embeddings.py  ← gera embeddings (sentence-transformers)
│   ├── cluster_games.py        ← clusteriza com K-means (experimental)
│   └── query_search.py         ← busca semântica interativa no terminal
│
└── docs/
    ├── DESIGN_BRIEF.md         ← direção visual e UX
    ├── DEVLOG.md               ← registro cronológico de decisões técnicas
    ├── ROADMAP.md              ← features planejadas
    └── ML.md                   ← documentação técnica do motor de ML

---

Como rodar

# instalar dependências (só para scripts Python)
pip install requests sentence-transformers numpy scikit-learn

# iniciar servidor
python3 server.py   # http://localhost:7432

O servidor:

• Serve os arquivos estáticos
• GET /api/config — retorna as API keys do .env pro browser
• POST /api/embed — proxy para HuggingFace (evita CORS)
• POST /games.json — salva dados com backup automático em backups/

Busca semântica no terminal

python3 scripts/query_search.py

query>   relaxing cozy puzzle exploration
similar> Hollow Knight --top 15
query>   challenging dark fantasy RPG --igdb 80

---

Variáveis de ambiente

# .env (não commitado — ver .env.example)
IGDB_CLIENT_ID=...
IGDB_CLIENT_SECRET=...
GROQ_API_KEY=gsk_...          # pipeline de enriquecimento
GEMINI_API_KEY=AIza...        # Game Agent (LLM)
HF_API_KEY=hf_...             # Game Agent (embeddings via proxy)
ANTHROPIC_API_KEY=sk-ant-...  # futuro reranker

---

Pipeline de enriquecimento

1. Metadata IGDB

python3 scripts/fetch_meta.py

2. Tags Steam

python3 scripts/fetch_steam_tags.py

3. Descrições LLM (Groq)

python3 scripts/enrich_groq_multi.py

Usa múltiplos modelos Groq em paralelo (~60 jogos/min, ~4h para 7k jogos). Prompt pede descrição de 60–80 palavras focada em gameplay feel — ritmo, atmosfera, tipo de desafio, tom emocional.

4. Embeddings

# Recomendado: Google Colab (T4 gratuita, ~2 min para 7k jogos)
python3 scripts/generate_embeddings.py

Modelo: BAAI/bge-large-en-v1.5 (1024 dims). Output: embeddings.bin (binário compacto, ~28MB).

---

Catálogo

Fonte: IGDB API · Filtro: rating ≥ 60 ou sem avaliações (jogos novos incluídos) · Plataformas: PS4/5, Xbox One/Series, Switch, PC, Mac, iOS, Android · Total: 7.034 jogos (sem corte de ano — clássicos incluídos)

---

Decisões técnicas

Por que single-file? Uso pessoal — zero overhead de build ou deploy. Abre direto no browser.

Por que Gemini 3.1 Flash Lite para o agente? 500 RPD gratuitos (vs 20 RPD do Gemini 3 Flash). Suporta tool calling com thoughtSignature, essencial para o loop de ferramentas.

Por que proxy local para HuggingFace? CORS impede chamadas diretas do browser para a API do HF. O server.py age como proxy em /api/embed.

Por que BAAI/bge-large-en-v1.5? 1024 dimensões, MTEB ~63.5 — melhor qualidade semântica que modelos menores. Encoding feito offline (Colab), não em tempo real.