Your AI-powered study assistant β chat, quiz, explain, summarize, and more.
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.
| 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 |
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
- Python 3.10+
- Node.js 18+
- Ollama (only required for the n8n local agent)
git clone https://github.com/ApyHtml20/PaperBrain.git
cd PaperBraincd backend
pip install -r requirements.txtCreate a .env file:
HF_TOKEN=your_huggingface_token HF_MODEL=Qwen/Qwen2.5-72B-Instruct SECRET_KEY=your_secret_key_here
Start the server:
uvicorn app.main:app --reload --port 8000
cd frontend
npm install
npm run dev# 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:
- Go to Workflows β Import
- Import
n8n/workflows/PaperBrain.json - Set the Ollama node URL to
http://localhost:11434 - Click Publish
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 |
| Method | Route | Description |
|---|---|---|
POST |
/api/auth/register |
Create a new account |
POST |
/api/auth/login |
Log in and receive a JWT token |
| 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 |
| 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 |
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=...
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)
- 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}/