- Início
- Descrição do Projeto
- Funcionalidades
- Arquitetura
- Execução
- Como gerar a Documentação do Código
- Testes
- Tecnologias utilizadas
- Diagrama de Classes
- Telas
- Pessoas Contribuidoras
- Licença
O sistema tem como objetivo ajudar os alunos a estudar através de resumos, flashcards, mapas mentais gerados por uma Large Language Model (LLM). Todas essas funcionalidades estarão em um só lugar de fácil acesso e com o conteúdo estruturado de forma a priorizar o entendimento da matéria/assunto em questão. Outro ponto interessante do sistema, é que ele foi idealizado para gamificar os estudos, utilizando por exemplo um sistema de Hot-Streak/Heatmap, onde o usuário deve estudar todos os dias para conseguir manter sua sequência de estudos.
O sistema têm como principais funcionalidades:
- Geração de resumos por uma LLM
- Geração de Mapas Mentais por uma LLM
- Geração Automática de Flashcards por uma LLM
- Geração Manual de Flashcards
- Funcionalidade de Download dos recursos gerados pela aplicação
- Discussão de dúvidas com modelos de IA capazes de serem um tutor pessoal.
- Sistema de Login/Criar Conta
- Armazenamento dos Conteúdos/FlashCards/Mapas Mentais na conta do Usuário
O sistema está idealizado para plataformas Web, onde o usuário irá entrar no site da aplicação, enviar um PDF e receber o resumo e as outras funcionalidades do sistema.
- Usuário envia um PDF.
- O documento é processado pelo PyMuPDF.
- O conteúdo é indexado no sistema RAG.
- A LLM gera:
- Resumos
- Flashcards
- Mapas mentais
- Os conteúdos são armazenados no PostgreSQL.
- O usuário pode acessar e revisar os materiais posteriormente.
A aplicação é executada com Docker Compose, que sobe quatro serviços: o
banco vetorial Qdrant, a LLM (Ollama), o backend (Flask, na porta
5000) e o frontend (Vite, na porta 5173).
Por default o Ollama roda em CPU, então funciona em qualquer máquina. Se
tiver GPU NVIDIA, dá para AUMENTAR BASTANTE A VELOCIDADE DE RESPOSTA DA LLM.
Os modelos ficam num volume persistente (ollama_data), então só são baixados
uma vez.
# 1. Clone o repositório
git clone https://github.com/lewislf/studex.git
cd studex
# Escolha entre rodar com GPU ou CPU.
# 2. Suba a aplicação (GPU)
# bash scripts/setup-gpu
# docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build
# 2. Suba a aplicação (CPU)
docker compose up --build
# 3. Baixe os modelos (só na primeira vez)
docker compose exec ollama ollama pull bge-m3 # embeddings
docker compose exec ollama ollama pull llama3.2 # geração (LLM)Após subir:
- Frontend: http://localhost:5173
- Backend (API): http://localhost:5000
- Qdrant: http://localhost:6333
Para rodar em segundo plano use docker compose up --build -d e, para encerrar,
docker compose down (use docker compose down -v só se quiser apagar também os
modelos e dados persistidos).
| Variável | Padrão | Descrição |
|---|---|---|
OLLAMA_HOST |
http://ollama:11434 |
Endereço do servidor Ollama |
OLLAMA_EMBED_HOST |
valor de OLLAMA_HOST |
Host do modelo de embeddings (se separado) |
OLLAMA_LLM_HOST |
valor de OLLAMA_HOST |
Host do modelo de geração (se separado) |
LLM_MODEL |
llama3.2:latest |
Modelo de geração usado pela LLM |
QDRANT_URL |
http://qdrant:6333 |
URL do banco vetorial Qdrant |
Para usar o Ollama instalado direto no host (reaproveitando modelos já
baixados), remova o serviço ollama e o depends_on: ollama do backend no
docker-compose.yml, e suba apontando a variável para o host:
OLLAMA_HOST=http://host.docker.internal:11434 docker compose up --buildA documentação do projeto será gerada automaticamente através das ferramentas JSDoc (front-end) e MkDocs (back-end).
Verifica se miniconda está instalado, cria conda env 'studex' e instala dependências.
# A partir da raiz do repositório "studex/"
bash scripts/install# A partir da raiz do repositório "studex/"
cd frontend
npm run docs
# Abra a documentação no navegador de sua preferência (Chrome, Firefox, Brave, etc.)
firefox docs/index.html# Lembre-se de ativar o Conda
conda init
source ~/.bashrc
# A partir da raiz do repositório "studex/"
cd backend
# Você pode gerar os arquivos estáticos na pasta site/ (Lembre-se de ativar o ambiente virtual)
mkdocs build
# Ou Servir localmente com hot-reload (abre em http://127.0.0.1:8000)
mkdocs serve
# Ou com Docker
docker compose up docsA documentação gerada pelo MkDocs (com o plugin mkdocstrings) é derivada das
docstrings do código Python, de forma análoga ao JSDoc.
Testes unitários utilizando PyTest para o Backend e Vitest para o Front-end
# Rodar testes unitários do Backend dentro do container (com a stack no ar)
docker compose exec backend python -m pytest
# Rodar testes unitários do Frontend dentro do container (com a stack no ar)
docker compose exec frontend npm run test- Git
- GitHub
- Miniconda
- npm
- Flask
- PostgreSQL
- PyMuPDF
- RAG (Retrieval Augmented Generation)
- Busca híbrida (Vetorial + BM25)
- RRF (Reciprocal Rank Fusion)
- Cohere Rerank 3
- text-embedding-3-small
- Gemini API
- Ollama
- Qwen
- Llama 3.2
- Phi-3.5 Mini
- PyTest
- React
- React Router
- Vite
- Mantine
- Tabler Icons
- Vitest
Este projeto está licenciado sob a licença MIT. Consulte o arquivo LICENSE para mais informações.


