🤖 patricIA — Course Assistant

Assistente de voz com IA para apresentações de curso. Fale uma pergunta → patricIA transcreve, busca no material do curso via RAG, gera uma resposta e fala de volta em português brasileiro.

🌐 Arquitetura

[Browser HTML/JS] ←WebSocket→ [FastAPI Backend]
     │                              │
     │              ┌───────────────┼───────────────┐
     │              │               │               │
     │     [faster-whisper]   [RAG/ChromaDB]  [XTTS v2]
     │         (STT)              (busca)        (TTS)

📁 Estrutura do Projeto

🏗️ Detalhes da Arquitetura

O patricIA segue uma arquitetura modular baseada em pipeline de processamento de voz:

[Navegador] ←WebSocket→ [Backend FastAPI]
                     ↓     ↓     ↓
                 [STT]  [RAG]  [LLM]  [TTS]

Cada componente é desacoplado e comunica-se através de interfaces bem definidas, tornando o sistema extensível e manutenível.

🧩 Componentes

• Frontend: HTML/CSS/JS vanilla que orbita na tela e captura áudio via WebRTC.
• Backend: FastAPI com endpoints WebSocket para comunicação real-time.
• STT: faster-whisper para transcrição em tempo real com suporte a português.
• RAG: Pipeline com ChromaDB e sentence-transformers para busca semântica no material do curso.
• LLM: Adaptador que suporta OpenRouter (modelos na nuvem) e Ollama (modelos locais).
• TTS: Coqui XTTS v2 com fallback para Microsoft Edge TTS.
• Gerenciador de Estado: Controla os estados do orb (idle, ouvindo, pensando, falando) e sincroniza com o frontend.

patricIA/
├── app.py            # FastAPI server + WebSocket pipeline
├── config.py         # Configuração centralizada
├── embedding.py      # Embeddings locais (all-MiniLM-L6-v2)
├── rag.py            # Pipeline RAG com ChromaDB
├── ingest.py         # CLI para ingerir .md no ChromaDB
├── llm.py            # Adapter LLM (OpenRouter / Ollama)
├── stt.py            # STT com faster-whisper
├── tts.py            # TTS com Coqui XTTS v2 (fallback: edge-tts)
├── orb.py            # Gerenciador de estado do orb
├── test_pipeline.py  # Testes de integração
├── requirements.txt  # Dependências Python
├── Dados/            # Coloque seus .md de curso aqui
└── static/
    ├── index.html    # Frontend
    ├── style.css     # Orb azul reativo
    └── app.js        # Cliente WebSocket

🚀 Setup

1. Instalar dependências do sistema

# ffmpeg (necessário para conversão MP3→WAV no edge-tts fallback)
# Ubuntu/Debian:
sudo apt install ffmpeg libportaudio2
# Fedora:
sudo dnf install ffmpeg portaudio
# macOS:
brew install ffmpeg portaudio

2. Instalar dependências Python via uv (Recomendado)

Compatibilidade: Python 3.10–3.14. Coqui-TTS requer PyTorch (GPU recomendada para XTTS v2). Recomendamos fortemente o uso do uv devido a sua alta velocidade.

Se ainda não tiver o uv instalado, instale com:

curl -LsSf https://astral.sh/uv/install.sh | sh

Para inicializar o projeto com dependências via uv:

cd ~/Projetos/patricIA
uv sync

Você também pode rodar comandos Python usando uv run, exemplo: uv run app.py.

(Alternativa Clássica via pip)

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Configurar variáveis de ambiente

# LLM (obrigatório para OpenRouter)
export PATRICIA_LLM_PROVIDER=openrouter
export PATRICIA_LLM_MODEL=anthropic/claude-sonnet-4
export OPENROUTER_API_KEY=sua-chave-aqui

# Ou usar Ollama local
export PATRICIA_LLM_PROVIDER=ollama
export PATRICIA_LLM_MODEL=llama3

3. Ingerir material do curso

Coloque arquivos .md na pasta Dados/ e rode:

python ingest.py --dir Dados/

Para resetar e reingerir:

python ingest.py --dir Dados/ --reset

4. Iniciar o servidor

# Com ingest automático
python app.py --ingest

# Sem ingest (se já ingeriu)
python app.py

# Host/port customizados
python app.py --host 0.0.0.0 --port 8000

5. Abrir no navegador

Acesse: http://localhost:8000

🎮 Controles

Ação	Como
Iniciar/parar gravação	Espaço ou clique no orb
Digitar pergunta	Via input de texto (se implementado)

🌀 Estados do Orb

Estado	Visual
Idle	Pulso suave, brilho calmo
Listening	Brilho intenso, anéis expansivos (ondas)
Thinking	Gradiente rotativo, rotação rápida
Speaking	Pulso vertical (boca), sincronizado com áudio

⚙️ Variáveis de Ambiente

Variável	Default	Descrição
PATRICIA_LLM_PROVIDER	openrouter	Provider LLM (openrouter ou ollama)
PATRICIA_LLM_MODEL	anthropic/claude-sonnet-4	Modelo LLM
OPENROUTER_API_KEY	—	API key do OpenRouter
PATRICIA_WHISPER_MODEL	base	Modelo Whisper (tiny, base, small)
PATRICIA_TTS_ENGINE	xtts	Engine TTS (xtts ou edge)
PATRICIA_PORT	8000	Porta do servidor
PATRICIA_CHUNK_SIZE	500	Tamanho dos chunks RAG
PATRICIA_RAG_TOP_K	3	Número de documentos recuperados
PATRICIA_CHROMA_DIR	.chroma/	Diretório do banco ChromaDB

🧪 Testes

python test_pipeline.py

⚠️ Notas

• Coqui XTTS v2 requer GPU para latência aceitável. Sem GPU, o fallback edge-tts é usado automaticamente.
• ffmpeg é necessário no sistema para conversão MP3→WAV (usado pelo edge-tts fallback).
• faster-whisper funciona em CPU com modelo base/tiny e compute_type=int8.
• O projeto NÃO usa LangChain — RAG direto com ChromaDB + sentence-transformers.
• Frontend é 100% vanilla HTML/CSS/JS — sem frameworks.
• Python 3.10–3.14 compatível. Coqui-TTS requer PyTorch.

📄 Licença

MIT