README.md

---
title: RAGStudy
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: static
license: mit
tags:
  - python
  - rag
  - study
---

# RAGStudy 🧠📚

RAGStudy é um assistente de estudos **offline** que lê PDFs de uma pasta local, constrói uma base de conhecimento e permite fazer perguntas em uma interface de chat, usando um LLM rodando localmente via LM Studio.

A ideia é funcionar como um “NotebookLM offline”, útil para quem estuda ou trabalha em ambientes com internet limitada (hospitais, campus universitário, plantas industriais, etc.), mas quer continuar usando IA de forma segura, privada e baseada nos próprios materiais (artigos, protocolos, capítulos de livro, slides, apostilas…).

---

## ✨ Principais funcionalidades

- 📁 **Leitura de PDFs locais**
  - Lê automaticamente todos os arquivos `.pdf` da pasta `materiais/`.
  - Extrai o texto e o organiza em parágrafos.

- 🧠 **RAG (Retrieval-Augmented Generation) simples**
  - Faz busca por termos nos parágrafos para encontrar trechos relevantes à pergunta.
  - Monta um contexto com as partes mais importantes antes de chamar o modelo de linguagem.

- 💬 **Interface em estilo chat**
  - Janela gráfica (Tkinter) que imita o fluxo de um chat.
  - Campo de texto para o usuário digitar qualquer pergunta.
  - Histórico de perguntas e respostas na própria interface.

- ⚡ **Atalhos rápidos de estudo**
  - Botões dedicados para:
    - **Resumo geral** dos PDFs.
    - **Pontos chave** para revisão rápida.
    - **Perguntas de estudo (quiz)** geradas a partir do conteúdo.

- 🔒 **100% local / offline**
  - Todos os PDFs ficam na máquina do usuário.
  - As perguntas e respostas são processadas usando um modelo local via LM Studio.
  - Nada é enviado para a nuvem.

---

## 🧱 Arquitetura resumida

1. O usuário coloca seus PDFs na pasta `materiais/`.
2. O RAGStudy:
   - extrai o texto com `pdfplumber`,
   - quebra em parágrafos,
   - salva uma base simples em `knowledge_base.json`.
3. Quando o usuário faz uma pergunta ou usa um atalho:
   - o sistema procura os parágrafos mais relevantes (keyword search),
   - monta um **contexto** com os trechos encontrados,
   - envia esse contexto + instruções para um modelo local via API (LM Studio).
4. O modelo retorna a resposta, que é exibida na interface de chat.

---

## 🛠️ Stack técnica

- **Linguagem:** Python
- **Leitura de PDFs:** [`pdfplumber`](https://github.com/jsvine/pdfplumber)
- **RAG:** busca simples por termos (keyword search) + montagem de contexto
- **LLM local:** LM Studio, com modelo do tipo:
  - `meta-llama-3.1-8b-instruct` (ou outro modelo Instruct compatível)
- **API local:** endpoint compatível com o padrão OpenAI Chat Completions  
  Exemplo de URL utilizada:
  - `http://127.0.0.1:1234/v1/chat/completions`
- **Interface gráfica:** Tkinter, com layout inspirado em chat (similar a ChatGPT)
- **Empacotamento opcional:** PyInstaller para gerar `.exe` e rodar com dois cliques

---

## 📂 Estrutura de pastas (recomendada)

```text
RAGStudy/
 ├─ RAGStudy.py          # Aplicação principal (GUI)
 ├─ requirements.txt
 ├─ README.md
 ├─ .gitignore
 ├─ materiais/           # Pasta onde o usuário coloca os PDFs
 └─ knowledge_base.json  # Gerado automaticamente (pode ser recriado)
```

> Obs.: em produção / controle de versão, é recomendado **não** subir a pasta `materiais/` nem o `knowledge_base.json` (eles podem conter dados pessoais ou sensíveis). Isso já pode ser controlado via `.gitignore`.

---

## ✅ Pré-requisitos

- Python 3.10+ instalado
- LM Studio instalado e configurado
- Um modelo Instruct compatível carregado no LM Studio  
  (por exemplo: `meta-llama-3.1-8b-instruct`)
- Servidor do LM Studio iniciado na porta 1234 (ou ajuste no código):

  - URL padrão utilizada no código:
    ```python
    LM_STUDIO_URL = "http://127.0.0.1:1234/v1/chat/completions"
    ```

---

## 🔧 Instalação e setup

1. **Clonar o repositório**

   ```bash
   git clone https://huggingface.co/Ojuaragabriel/RAGStudy
   cd RAGStudy
   ```

2. **Criar e ativar um ambiente virtual (recomendado)**

   **Windows (PowerShell):**

   ```bash
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   ```

   **Linux / macOS:**

   ```bash
   python -m venv .venv
   source .venv/bin/activate
   ```

3. **Instalar as dependências**

   ```bash
   pip install -r requirements.txt
   ```

4. **Criar a pasta de materiais**

   Na raiz do projeto:

   ```bash
   mkdir materiais
   ```

   Coloque dentro dela os PDFs que você quer usar no estudo.

---

## ▶️ Execução

1. **No LM Studio:**
   - Abra o LM Studio.
   - Carregue um modelo do tipo Instruct (ex.: `meta-llama-3.1-8b-instruct`).
   - Inicie o servidor (API) na porta 1234 (ou ajuste o código se usar outra porta).

2. **No terminal (com venv ativa):**

   ```bash
   python RAGStudy.py
   ```

3. A interface de chat será aberta. Nela você pode:

   - Clicar em **Recarregar PDFs** para montar/atualizar a base de conhecimento.
   - Usar os atalhos:
     - **Resumo geral**
     - **Pontos chave**
     - **Perguntas de estudo**
   - Digitar qualquer pergunta no campo inferior e enviar.

---

## 💡 Possíveis usos

- Revisão rápida de artigos científicos.
- Estudo de protocolos, diretrizes e normas em ambientes com internet limitada.
- Apoio em disciplinas da graduação (engenharias, saúde, exatas, etc.).
- Criação de quizzes personalizados a partir dos próprios materiais.

---

## 🚀 Próximos passos / ideias de evolução

- Substituir a busca por termos por um RAG vetorial (FAISS / Chroma / etc.).
- Adicionar suporte a outros formatos além de PDF (Markdown, DOCX, HTML).
- Perfil por “coleções de estudo” (pastas separadas por disciplina ou tema).
- Versão web com Gradio ou FastAPI.
- Configurar modelos alternativos (por exemplo outros LLaMA, Qwen, Mistral, etc.).

---

## 👤 Autor

Desenvolvido por **Gabriel Cerqueira (@Ojuaragabriel)** como projeto pessoal de:

- experimentação com GenAI **offline**,
- estudo de RAG (Retrieval-Augmented Generation),
- construção de ferramentas de estudo baseadas em PDFs próprios, mantendo privacidade e controle dos dados.