Skip to content
lewislfPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

studex_logo

Índice

Descrição

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.

Funcionalidades

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

Arquitetura

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.

Fluxo Geral

  1. Usuário envia um PDF.
  2. O documento é processado pelo PyMuPDF.
  3. O conteúdo é indexado no sistema RAG.
  4. A LLM gera:
    • Resumos
    • Flashcards
    • Mapas mentais
  5. Os conteúdos são armazenados no PostgreSQL.
  6. O usuário pode acessar e revisar os materiais posteriormente.

Execução

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.

Pré-requisitos

# 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:

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áveis de ambiente relevantes (backend)

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

Rodar o Ollama no host em vez do container (opcional)

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 --build

Documentação do Código

A documentação do projeto será gerada automaticamente através das ferramentas JSDoc (front-end) e MkDocs (back-end).

Pré-requisito

Verifica se miniconda está instalado, cria conda env 'studex' e instala dependências.

# A partir da raiz do repositório "studex/"
bash scripts/install

Como gerar documentação para o front-end

# 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

Como gerar documentação para o back-end

# 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 docs

A documentação gerada pelo MkDocs (com o plugin mkdocstrings) é derivada das docstrings do código Python, de forma análoga ao JSDoc.

Testes

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

Tecnologias Utilizadas

DevOps e Ferramentas

  • Git
  • GitHub
  • Miniconda
  • npm

Back-End

  • 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

Front-End

  • React
  • React Router
  • Vite
  • Mantine
  • Tabler Icons
  • Vitest

Diagrama de Classes

StudexUML

Telas

home revisao estatisticas image

Contribuidores

Artur Felipe Luis

Licença

Este projeto está licenciado sob a licença MIT. Consulte o arquivo LICENSE para mais informações.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages