{"repo": "alex-data9/chatbot-rag", "files": {"README.md": {"9e0a8e35957dfb5b23462eb717dfd8a0dacbf956": {"t": 1785746396.9569423, "n": 11983, "h": "be8937eeadadd4e7", "c": "# 🤖 Sofia — Chatbot RAG com DeepSeek + LangChain + FastAPI\n\nUm assistente virtual inteligente para atendimento de marketing em instituições de ensino, alimentado por RAG (Retrieval-Augmented Generation) com DeepSeek API, LangChain, ChromaDB e FastAPI.\n\n**Status:** ✅ Funcional | RAG vazio (aguardando PDFs)\n**Modelo:** DeepSeek Chat (deepseek-chat)\n**Framework:** FastAPI + LangChain + ChromaDB\n**Frontend:** React-like vanilla JS com Dark Theme\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.10+\n- DeepSeek API Key (https://platform.deepseek.com)\n\n### Instalação & Execução\n\n#### 1. Backend (FastAPI)\n```bash\ncd backend\npip install -r requirements.txt\n\n# Criar arquivo .env\necho 'DEEPSEEK_API_KEY=sk-seu-token-aqui' > .env\n\n# Rodar servidor\npython -m uvicorn app.main:app --host 0.0.0.0 --port 8000\n```\n\n#### 2. Frontend (Standalone)\n```bash\ncd frontend\npython -m http.server 8080\n```\n\n#### 3. Acessar\n- **Interface Web:** http://localhost:8080\n- **API Docs:** http://localhost:8000/docs (Swagger UI)\n- **Health Check:** http://localhost:8000/api/health\n\n---\n\n## 📋 Estrutura do Projeto\n\n```\nchatbot-rag/\n├── backend/\n│   ├── app/\n│   │   ├── main.py                 # FastAPI entry point\n│   │   ├── config.py               # Settings via Pydantic\n│   │   ├── agent/\n│   │   │   ├── prompts.py          # System prompt \"Sofia\"\n│   │   │   └── profiles.py         # Lead profile detection\n│   │   └── rag/\n│   │       ├── chain.py            # RAG conversational chain\n│   │       ├── ingest.py           # PDF ingestion pipeline\n│   │       └── retriever.py        # ChromaDB retriever\n│   ├── .env                        # API Keys (git-ignored)\n│   ├── .env.example                # Template\n│   ├── requirements.txt            # Python dependencies\n│   └── test_rag.py                 # CLI tester\n│\n├── frontend/\n│   ├── index.html                  # Main HTML\n│   ├── style.css                   # Dark theme styling\n│   ├── app.js                      # Client-side logic\n│   └── (assets served as-is)\n│\n└── README.md                        # Este arquivo\n```\n\n---\n\n## 🔧 Configuração\n\n### Backend (.env)\n```env\n# DeepSeek API\nDEEPSEEK_API_KEY=sk-...\nDEEPSEEK_BASE_URL=https://api.deepseek.com\n\n# Supabase (optional, future use)\nSUPABASE_URL=\nSUPABASE_SERVICE_KEY=\nSUPABASE_ANON_KEY=\n\n# Resend Email (optional)\nRESEND_API_KEY=\nEMAIL_FROM=chatbot@instituicao.com\nEMAIL_MARKETING=marketing@instituicao.com\n\n# Scheduling\nDAILY_REPORT_HOUR=23\nDAILY_REPORT_MINUTE=59\n```\n\n### Variáveis de Configuração (appsettings)\nEditáveis em `backend/app/config.py`:\n\n| Variável | Padrão | Descrição |\n|----------|--------|-----------|\n| `llm_model` | `deepseek-chat` | Modelo LLM |\n| `embedding_model` | `text-embedding-3-small` | Embedding model (OpenAI) |\n| `pdf_dir` | `data/pdfs` | Diretório de PDFs |\n| `vectorstore_dir` | `data/vectorstore` | Persistência ChromaDB |\n| `chunk_size` | `1000` | Tamanho dos chunks |\n| `chunk_overlap` | `200` | Overlap entre chunks |\n| `retriever_k` | `4` | Top-k docs para retrieval |\n\n---\n\n## 📡 API Endpoints\n\n### Health Check\n```bash\nGET /api/health\n```\n**Response (RAG vazio):**\n```json\n{\n  \"status\": \"ok\",\n  \"vectorstore_ready\": false,\n  \"chain_ready\": false,\n  \"rag_empty\": true,\n  \"model\": \"deepseek-chat\"\n}\n```\n\n### Chat Síncrono\n```bash\nPOST /api/chat\nContent-Type: application/json\n\n{\n  \"message\": \"Quais cursos vocês oferecem?\",\n  \"session_id\": \"default\"\n}\n```\n\n**Response (RAG vazio):**\n```json\n{\n  \"response\": null,\n  \"session_id\": \"default\",\n  \"rag_empty\": true\n}\n```\n\n**Response (RAG populado):**\n```json\n{\n  \"response\": \"Olá! Somos uma instituição de ensino...\",\n  \"session_id\": \"default\",\n  \"rag_empty\": false\n}\n```\n\n### Chat com Streaming (SSE)\n```bash\nPOST /api/chat/stream\nContent-Type: application/json\n\n{\n  \"message\": \"Quais cursos vocês oferecem?\",\n  \"session_id\": \"default\"\n}\n```\n\nRetorna tokens via Server-Sent Events em tempo real.\n\n### Reset Conversa\n```bash\nPOST /api/chat/reset?session_id=default\n```\n\nLimpa histórico da sessão.\n\n### Encerrar Conversa + Resumo\n```bash\nPOST /api/chat/end?session_id=default\n```\n\n**Response:**\n```json\n{\n  \"summary\": \"Lead interessado em cursos de TI...\",\n  \"session_id\": \"default\"\n}\n```\n\n### Re-indexar PDFs (Admin)\n```bash\nPOST /api/ingest?force=true\n```\n\n**Workflow:**\n1. Coloca PDFs em `backend/data/pdfs/`\n2. Chama `POST /api/ingest`\n3. Backend carrega, divide em chunks, gera embeddings, persiste no ChromaDB\n\n---\n\n## 🧠 Lógica RAG\n\n### Pipeline de Ingestão\n```\nPDFs (data/pdfs/)\n    ↓\nDirectoryLoader + PyPDFLoader\n    ↓\nDocumentos com metadados (filename, category, page)\n    ↓\nRecursiveCharacterTextSplitter (1000 chars, 200 overlap)\n    ↓\nChunks\n    ↓\nOpenAIEmbeddings (text-embedding-3-small)\n    ↓\nChromaDB (persistent em data/vectorstore/)\n```\n\n### Fluxo de Chat\n```\nUser Message\n    ↓\nRetriever: similarity search (top-4 chunks)\n    ↓\nFormat Context: [Source | Category | Page | Content]\n    ↓\nPrompt Template:\n  - System: Sofia persona + 7-step flow\n  - History: últimas mensagens\n  - Context: chunks recuperados\n  - Input: mensagem do usuário\n    ↓\nDeepSeek LLM (temperature=0.7)\n    ↓\nStrOutputParser\n    ↓\nResponse + History Update\n```\n\n---\n\n## 👤 Sistema de Perfis de Lead\n\nDetecta automaticamente o tipo de aluno:\n\n| Perfil | Trigger | Foco |\n|--------|---------|------|\n| **VESTIBULANDO** | \"primeiro curso\", \"saída do ensino médio\" | Primeiro emprego, estágio, campus life |\n| **PROFISSIONAL** | \"já trabalho\", \"carreira\" | Flexibilidade, EAD, crescimento salarial |\n| **TRANSFERIDO** | \"transferência\", \"outra faculdade\" | Aproveitamento de disciplinas |\n| **PÓS-GRADUANDO** | \"especialização\", \"master\" | Aprofundamento, networking |\n| **PAI/MÃE** | \"meu filho\", \"minha filha\" | Segurança, empregabilidade, financiamento |\n\n---\n\n## 💬 Sofia — System Prompt\n\n**Propósito:** Consultora de matrículas com tom ACOLHEDOR, PROFISSIONAL e ENTUSIASMADO.\n\n**7 Etapas de Atendimento:**\n1. **Boas-vindas** — Cumprimento + identificação de perfil\n2. **Apresentação do Curso** — Destáques, grade, modalidade\n3. **Mercado de Trabalho** — Empregabilidade, salário, parceiros\n4. **Estrutura Institucional** — Infraestrutura, MEC, acreditações\n5. **Financeiro** — Mensalidade, FIES, ProUni, bolsas, ROI\n6. **Call-to-Action** — Inscrição, visita, consultor, email/telefone\n7. **Escalation** — Transfer para humano se necessário\n\n**Contorno de Objeções:**\n- \"É muito caro\" → FIES, ProUni, bolsas, ROI\n- \"Não tenho tempo\" → EAD, híbrido, noturno, flexibilidade\n- \"Não sei se é para mim\" → Perfil quiz, cursos alternativos\n- \"Vou pensar\" → Urgência real (prazo inscrição, vagas)\n- \"Já pesquisei outros\" → Comparação direta, diferenciais\n\n**Regras Obrigatórias:**\n- ✅ Sempre português do Brasil\n- ✅ Coletar nome + email OU telefone\n- ✅ Basear TUDO em contexto do knowledge base\n- ✅ Max 3-4 parágrafos por resposta\n- ❌ NUNCA inventar dados/preços/notas\n- ❌ NUNCA discussões fora do escopo educacional\n\n---\n\n## 🎨 Frontend Features\n\n### Componentes\n- **Sidebar** com navegação (Chat, Status)\n- **Chat Panel** com histórico scrollable\n- **Welcome Screen** com quick actions\n- **Status Page** com health check em tempo real\n- **Input Zone** com suporte a markdown\n- **RAG Empty Banner** com aviso amarelo\n\n### Atalhos de Teclado\n- `Enter` — Enviar mensagem\n- `Shift+Enter` — Nova linha\n- Textarea auto-redimensiona\n\n### Dark Theme\n- Background: `#0f0f14` (off-black)\n- Accent: `#6c5ce7` (purple)\n- Text: `#e8e8ed` (light gray)\n- Gradients suaves nas CTAs\n\n---\n\n## 🔐 Segurança\n\n### Produção\n- [ ] Restringir CORS a domínios específicos\n- [ ] Usar HTTPS + TLS\n- [ ] Implementar rate limiting\n- [ ] Validar e sanitizar entrada JSON\n- [ ] Usar per-user sessions (não global chain)\n- [ ] Armazenar embeddings + histórico no Supabase\n- [ ] JWT tokens para admin endpoints\n\n### Atual (Dev)\n- ✅ CORS habilitado globalmente (dev convenience)\n- ✅ Global chain (single-session)\n\n---\n\n## 📊 Estrutura de Dados\n\n### Document Metadata\n```python\n{\n  \"source\": \"/path/to/file.pdf\",\n  \"file_name\": \"file.pdf\",\n  \"category\": \"cursos|institucional|mercado|atendimento|geral\",\n  \"page\": 1\n}\n```\n\n### Message History\n```python\n[\n  HumanMessage(content=\"Olá!\"),\n  AIMessage(content=\"Oi! Bem-vindo...\"),\n  HumanMessage(content=\"Quais cursos?\"),\n  AIMessage(content=\"Ofereçemos...\"),\n]\n```\n\n### ChromaDB Collection\n- **Name:** `chatbot_rag`\n- **Embeddings:** OpenAI text-embedding-3-small\n- **Persistence:** `backend/data/vectorstore/`\n- **Documents:** Auto-indexed com metadata\n\n---\n\n## 🛠️ Desenvolvimento\n\n### Instalar Dependências para Dev\n```bash\ncd backend\npip install -r requirements.txt\npip install pytest jupyter  # optional\n```\n\n### Rodar Testes\n```bash\npython test_rag.py\n# ou use a CLI interativa\n```\n\n### Modo Debug\n```bash\nDEEPSEEK_API_KEY=sk-... python -m uvicorn app.main:app --reload --log-level debug\n```\n\n### Adicionar Nova Rota\n```python\n@app.post(\"/api/custom\")\nasync def custom_endpoint(request: SomeModel):\n    # logic\n    return {\"result\": \"...\"}\n```\n\n---\n\n## 🚀 Deploy\n\n### Docker (Future)\n```dockerfile\nFROM python:3.10-slim\nWORKDIR /app\nCOPY backend/requirements.txt .\nRUN pip install -r requirements.txt\nCOPY backend/app ./app\nCMD [\"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]\n```\n\n### Vercel/Fly.io (Future)\n- Frontend: Static files → Vercel\n- Backend: FastAPI → Fly.io ou Railway\n\n---\n\n## 🐛 Troubleshooting\n\n### \"ModuleNotFoundError: langchain.text_splitter\"\n**Solução:**\n```python\n# ❌ Errado\nfrom langchain.text_splitter import RecursiveCharacterTextSplitter\n\n# ✅ Correto\nfrom langchain_text_splitters import RecursiveCharacterTextSplitter\n```\n\n### RAG vazio / Chain não inicializa\n**Verifique:**\n1. Há PDFs em `backend/data/pdfs/`?\n2. Execute `POST /api/ingest?force=true`\n3. Verifique `backend/data/vectorstore/` foi criado\n\n### CORS errors (Frontend)\n**Dev workaround:** O backend já tem `allow_origins=[\"*\"]`\n**Produção:** Ajuste em `app/main.py` line 76\n\n### DeepSeek API Key inválida\n```bash\n# Teste a conexão\ncurl -X POST https://api.deepseek.com/chat/completions \\\n  -H \"Authorization: Bearer sk-seu-token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"deepseek-chat\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Teste\"}]\n  }'\n```\n\n---\n\n## 📅 Roadmap\n\n- [ ] Integração Supabase (persistir conversas)\n- [ ] Email reports via Resend\n- [ ] APScheduler para relatórios diários\n- [ ] Score-threshold retriever (evitar irrelevantes)\n- [ ] Per-user sessions (não global)\n- [ ] WebSocket support (em vez de SSE)\n- [ ] Admin dashboard (ingestão visual)\n- [ ] Analytics (conversão, tópicos)\n- [ ] Multi-language support\n- [ ] Integração WhatsApp/Telegram\n\n---\n\n## 📝 Changelog\n\n### v2.1.0 (Current)\n- ✅ Frontend estático (vanilla JS)\n- ✅ Suporte RAG vazio (retorna null + rag_empty flag)\n- ✅ Migração DeepSeek (OpenAI → DeepSeek API)\n- ✅ Dark theme moderno\n- ✅ Health check + status page\n\n### v2.0.0 (Initial)\n- FastAPI + LangChain + ChromaDB\n- Sofia persona + 7-step flow\n- PDF ingestion pipeline\n- Session management\n\n---\n\n## 🤝 Contribuindo\n\n1. Clone o repo\n2. Crie uma branch (`git checkout -b feature/nome`)\n3. Commit (`git commit -am 'Add feature'`)\n4. Push (`git push origin feature/nome`)\n5. Abra um Pull Request\n\n---\n\n## 📄 Licença\n\nMIT License — Veja [LICENSE](LICENSE) para detalhes.\n\n---\n\n## 👥 Autores\n\n- **Claude Code** — AI Assistant\n- **Alex Data** — Projeto Original\n\n---\n\n## 💬 Suporte\n\nPara questões ou bugs:\n1. Abra uma [Issue no GitHub](https://github.com/Alex-data9/chatbot-rag/issues)\n2. Verifique os troubleshooting acima\n3. Consulte a documentação do LangChain/FastAPI\n\n---\n\n## 🎯 Status do Projeto\n\n| Componente | Status | Notas |\n|------------|--------|-------|\n| Backend API | ✅ Live | Porta 8000 |\n| Frontend | ✅ Live | Porta 8080 |\n| RAG | ⚠️ Vazio | Aguardando PDFs |\n| DeepSeek Integration | ✅ Pronto | API key no .env |\n| Supabase | 🔄 Planejado | Fase 2 |\n| Email Reports | 🔄 Planejado | Fase 2 |\n| Per-user Sessions | 🔄 Planejado | Fase 2 |\n\n---\n\n**🚀 Pronto para usar! Coloque seus PDFs em `backend/data/pdfs/` e boa sorte!**\n"}}}}