PaperBrain

Your AI-powered study assistant — chat, quiz, explain, summarize, and more.

---

What is PaperBrain?

PaperBrain turns your documents into an interactive study session. Upload a PDF, ask questions about it, generate a quiz, get flashcards, or request a plain-English explanation — all in one place.

It runs on a FastAPI + React stack with Qwen 2.5-72B via HuggingFace for cloud inference, ChromaDB for document retrieval (RAG), and an optional local n8n AI Agent powered by Ollama for fully offline automation.

---

Features

	Feature	Description
💬	General Chat	Study assistant backed by Qwen 2.5-72B
📄	RAG Mode	Ask questions directly about your uploaded documents
🧪	Quiz	Auto-generated multiple-choice quizzes on any topic
🃏	Flashcards	Smart cards for active recall and memorization
💡	Explain	Concept breakdowns at beginner / intermediate / advanced level
📝	Summarize	Auto-summarize any text or uploaded document
📁	Document Manager	Upload PDF, TXT, DOCX — indexed per user with isolation
👤	Auth	JWT-based register/login with per-user data separation
📊	Profile & Stats	Quiz history, streaks, and progression tracking
🔄	n8n AI Agent	Local agent with Ollama (llama3.1 / Qwen 2.5) + 5 tools

---

Architecture

PaperBrain/
├── backend/ # FastAPI Python backend
│ ├── app/
│ │ ├── auth/
│ │ │ ├── jwt_handler.py # JWT token creation/decoding
│ │ │ └── middleware.py # get_current_user dependency
│ │ ├── db/
│ │ │ ├── database.py # SQLite + SQLAlchemy setup
│ │ │ ├── models.py # User, QuizResult, StudySession
│ │ │ └── crud.py # DB operations
│ │ ├── tools/ # AI tool modules
│ │ ├── agent.py # Main AI dispatcher
│ │ ├── ingest.py # Document ingestion + chunking
│ │ ├── rag.py # ChromaDB vector store
│ │ ├── router_service.py # API routes
│ │ ├── schemas.py # Pydantic request models
│ │ └── main.py # FastAPI app entry point
│ ├── Dockerfile
│ └── requirements.txt
├── frontend/ # React frontend
│ └── src/
│ └── pages/
│ ├── Chat.jsx
│ ├── Quiz.jsx
│ ├── Flashcards.jsx
│ ├── Documents.jsx
│ └── Profile.jsx
├── n8n/ # Local n8n AI Agent
│ └── workflows/
│ └── PaperBrain.json
└── docs/
├── logo.png
└── n8n-workflow.png

---

Local Setup

Prerequisites

• Python 3.10+
• Node.js 18+
• Ollama (only required for the n8n local agent)

1 — Clone the repository

git clone https://github.com/ApyHtml20/PaperBrain.git
cd PaperBrain

2 — Backend

cd backend
pip install -r requirements.txt

Create a .env file:

HF_TOKEN=your_huggingface_tokenHF_MODEL=Qwen/Qwen2.5-72B-InstructSECRET_KEY=your_secret_key_here

Start the server:

uvicorn app.main:app --reload --port 8000

3 — Frontend

cd frontend
npm install
npm run dev

4 — n8n + Ollama (optional)

# Install and start Ollama, then pull the model
ollama pull llama3.1
# Install and start n8n
npm install -g n8n
n8n start
# → http://localhost:5678

Then in n8n:

1. Go to Workflows → Import
2. Import n8n/workflows/PaperBrain.json
3. Set the Ollama node URL to http://localhost:11434
4. Click Publish

---

n8n AI Agent

The local n8n agent orchestrates all learning tools automatically using Ollama llama3.1 — no cloud required.

[Postman / Frontend]
↓
[AI Agent (RAG)] ←→ [Ollama — llama3.1]
↓
┌─────┴─────────────────────────────────┐
│ │ │ │ │
[Flashcards] [Explain] [RAG] [Summarize] [Quiz]
↓
[Frontend Output]

Tool	What it does
🃏 Flashcards	Generate flashcards on any topic
💡 Explain	Explain a concept at any depth
📄 RAG	Search your uploaded documents
📝 Summarize	Summarize topics automatically
🧪 Quiz	Generate multiple-choice questions

---

API Reference

Auth

Method	Route	Description
POST	/api/auth/register	Create a new account
POST	/api/auth/login	Log in and receive a JWT token

Learning (requires auth)

Method	Route	Description
POST	/api/chat	General AI chat
POST	/api/rag-qa	Chat with your documents
POST	/api/quiz	Generate an MCQ quiz
POST	/api/flashcards	Generate flashcards
POST	/api/explain	Explain a concept
POST	/api/resume	Summarize text

Documents (requires auth)

Method	Route	Description
GET	/api/documents	List your documents
POST	/api/upload	Upload a PDF, TXT, or DOCX file
DELETE	/api/documents/{filename}	Delete a document

---

Deploying to Hugging Face Spaces

FROM python:3.11-slim
WORKDIR /code
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

Add these under Settings → Variables and secrets:

HF_TOKEN=...
HF_MODEL=Qwen/Qwen2.5-72B-Instruct
SECRET_KEY=...

---

Tech Stack

Backend — FastAPI · SQLite + SQLAlchemy · ChromaDB · HuggingFace InferenceClient · python-jose · pdfplumber · python-docx

Frontend — React 18 · Vite

Local AI — n8n · Ollama · llama3.1

Deployment — Hugging Face Spaces (Docker)

---

Security

• Passwords hashed with SHA-256 + random salt
• JWT tokens expire after 24 hours
• All routes protected by auth middleware
• Documents and ChromaDB collections isolated by user_id
• Files stored under documents/{user_id}/

---

Live Demo

🔗 huggingface.co/spaces/ApyHTML19/PaperBrainAI