| --- |
| title: RPG-RAG |
| emoji: 🎲 |
| colorFrom: purple |
| colorTo: blue |
| sdk: gradio |
| sdk_version: "6.9.0" |
| python_version: "3.12" |
| app_file: app.py |
| pinned: false |
| --- |
| |
|
|
| # RPG-RAG |
|
|
| Um kit pessoal para organizar **lore/campanhas de RPG** e usar **LLMs locais** pra ajudar durante e depois das sessões. |
|
|
| O repositório hoje tem 3 “pilares” principais: |
|
|
| 1. **Session Helper (Tkinter)**: seleciona uma campanha, transcreve um áudio e gera um resumo via Ollama. |
| 2. **UI protótipo (PyQt6)**: um menu básico para futuramente unir geração + pós-sessão. |
| 3. **PDF reader (PyMuPDF)**: extrai texto de PDFs e detecta imagens (com placeholder para descrever as imagens). |
|
|
| > Status: o projeto está em desenvolvimento e algumas partes ainda são rascunhos (ex.: `src/brain.py`, `src/get_data.py`, geradores em `src/gen/`). |
| |
| ## Funcionalidades |
| |
| - **Campanhas**: carrega campanhas em `Data/Campaings/campaings.json`. |
| - **Transcrição**: usa Whisper para transcrever arquivo de áudio (ex.: MP3). |
| - **Resumo**: usa um LLM via **Ollama** pra resumir a sessão. |
| - **Extração de PDF**: pega texto e imagens e salva imagens extraídas. |
| |
| ## Estrutura do projeto |
| |
| - `Data/` |
| - `Campaings/`: campanhas e sessões |
| - `Ekalia/`: lore/mundo em `.txt` (obsidian-friendly) |
| - `Audios/`: exemplos de áudio |
| - `src/` |
| - `main.py`: app Tkinter (Session Helper) |
| - `main2.py`: protótipo PyQt6 |
| - `ears/whisper.py`: transcrição e resumo |
| - `pdf_reader/pdf_agent.py`: extrator de PDF (texto + imagens) |
| - `brain.py`: experimentos com agentes/LLM (atenção: contém prompts inadequados e não representa o objetivo final) |
| - `get_data.py`: experimento para ler dados e jogar em dataframe (precisa de ajustes) |
| - `models/`: modelos locais (ex.: qwen) |
|
|
| ## Pré-requisitos |
|
|
| - Python 3.10+ (recomendado) |
| - (Opcional) GPU/CUDA para Whisper acelerar — funciona em CPU também. |
| - **Ollama instalado e rodando** (para o resumo): https://ollama.com |
|
|
| ## Instalação |
|
|
| Crie um ambiente virtual e instale dependências: |
|
|
| ```bash |
| python -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
|
|
| ## Como rodar |
|
|
| ### 1) Session Helper (Tkinter) |
|
|
| Abre uma UI simples para: |
|
|
| - listar campanhas |
| - selecionar campanha |
| - escolher um arquivo de áudio |
| - transcrever e gerar resumo |
|
|
| ```bash |
| python src/main.py |
| ``` |
|
|
| **Observações** |
|
|
| - O arquivo de campanhas precisa existir em `Data/Campaings/campaings.json`. |
| - O resumo usa Ollama via LangChain. Ajuste o modelo em `src/ears/whisper.py` (variável `LLM_MODEL`). |
|
|
| ### 2) Protótipo de UI (PyQt6) |
|
|
| Interface base com navegação de telas. |
|
|
| ```bash |
| python src/main2.py |
| ``` |
|
|
| ### 3) Extrator de PDF |
|
|
| Processa um PDF e salva imagens encontradas em `extracted_images/`. |
|
|
| ```bash |
| python src/pdf_reader/pdf_agent.py |
| ``` |
|
|
| Por padrão o script tenta ler `DH.pdf` na raiz. Se não existir, edite `test_pdf_path` no final do arquivo. |
|
|
| ## LLM Local com vLLM (opcional) |
|
|
| O projeto suporta rodar um LLM local via [vLLM](https://github.com/vllm-project/vllm) |
| como alternativa à API da Groq. Útil pra desenvolvimento offline, custos zero |
| e (futuramente) servir modelos fine-tuned. |
|
|
| ### Por que um venv separado |
|
|
| vLLM tem requisitos rígidos de torch/CUDA que conflitam com Whisper e |
| `langchain-huggingface` no venv principal. A solução padrão é isolar o vLLM |
| em seu próprio ambiente — o projeto principal só conversa com ele via HTTP. |
|
|
| ``` |
| .venv/ ← venv principal (Whisper, FAISS, embeddings, gradio…) |
| .venv-vllm/ ← venv isolado, só com vllm + suas deps CUDA |
| ``` |
|
|
| ### Setup (uma vez) |
|
|
| Pré-requisito: GPU NVIDIA com pelo menos 16GB VRAM (testado em RTX 5060 Ti). |
|
|
| ```bash |
| uv venv .venv-vllm --python 3.12 |
| uv pip install --python .venv-vllm/bin/python vllm --torch-backend=auto |
| ``` |
|
|
| A flag `--torch-backend=auto` deixa o uv detectar a versão do CUDA pelo |
| `nvidia-smi` e baixar o wheel compatível. Em GPUs Blackwell (RTX 50xx) com |
| driver recente isso é o stack CUDA 13. |
|
|
| ### Subindo o servidor |
|
|
| ```bash |
| python vllm/run_local.py |
| ``` |
|
|
| O script: |
| - Aponta pro binário em `.venv-vllm/bin/vllm` |
| - Configura `LD_LIBRARY_PATH` pra encontrar os `.so` de CUDA do venv isolado |
| - Sobe um servidor **OpenAI-compatible** em `http://localhost:8000/v1` |
| - Modelo padrão: `Qwen/Qwen2.5-7B-Instruct-AWQ` (4-bit, cabe folgado em 16GB) |
|
|
| Primeira execução baixa o modelo (~5GB) em `vllm/Models/` (ignorado pelo git). |
|
|
| ### Usando no código |
|
|
| `src/llm/client.py` expõe três papéis (`Role`): |
|
|
| ```python |
| from src.llm.client import get_llm, Role |
| |
| llm = get_llm(Role.FAST) # → Groq llama-3.1-8b-instant (padrão) |
| llm = get_llm(Role.CREATIVE) # → Groq llama-3.3-70b-versatile |
| llm = get_llm(Role.LOCAL) # → vLLM local (Qwen2.5-7B-AWQ) |
| ``` |
|
|
| `Role.LOCAL` usa `ChatOpenAI` apontando pro endpoint local — não precisa de |
| nenhum SDK específico do vLLM. |
|
|
| ### Variáveis de ambiente (opcionais) |
|
|
| Todas têm default sensato; só sobrescreva no `.env` se precisar mudar: |
|
|
| | Variável | Default | Para quê | |
| | --- | --- | --- | |
| | `VLLM_BASE_URL` | `http://localhost:8000/v1` | URL do servidor local | |
| | `VLLM_MODEL` | `Qwen/Qwen2.5-7B-Instruct-AWQ` | Modelo servido pelo vLLM | |
| | `VLLM_API_KEY` | `EMPTY` | Token (vLLM aceita qualquer string por padrão) | |
|
|
| ### Smoke test |
|
|
| Com o servidor rodando em outro terminal: |
|
|
| ```bash |
| python -m src.llm.client --local |
| ``` |
|
|
| Deve imprimir uma resposta do Qwen local. Sem `--local`, usa Groq (`Role.CREATIVE`) |
| — bom pra confirmar que o fallback continua funcionando. |
|
|
| --- |
|
|
| ## Notas importantes / TODOs |
|
|
| - `src/brain.py` contém experimentos com agentes e prompts de teste. Use como referência de experimentação, não como “produção”. |
| - `src/get_data.py` tem um bug (tenta imprimir `context['file_path']` mas a chave criada é `file name`). |
| - Os geradores em `src/gen/` estão vazios no momento. |
| - `src/main.py` tem um TODO antigo: “Trocar Tkinter por PySide6”. Hoje há um protótipo em PyQt6 (`main2.py`). |
|
|
| ## Troubleshooting |
|
|
| ### Whisper muito lento |
|
|
| - Em CPU, o Whisper (principalmente `large`) pode demorar bastante. |
| - Você pode trocar o modelo em `src/ears/whisper.py` (ex.: `base`, `small`, `medium`, `large`). |
|
|
| ### Ollama não responde |
|
|
| - Garanta que o daemon do Ollama está rodando. |
| - Garanta que o modelo configurado em `LLM_MODEL` existe (ex.: `ollama pull deepseek-r1:latest`). |
|
|
| ## Licença |
|
|
| Se você quiser, posso adicionar uma licença explícita (MIT/Apache-2.0/etc). Por enquanto, o repositório não declara licença aqui no README. |
|
|
