Skip to content

README.md

Latest commit

 

History

History
260 lines (198 loc) · 7.54 KB

README.md

File metadata and controls

260 lines (198 loc) · 7.54 KB
Raw

PaperBrain Logo

PaperBrain

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

PaperBrain screenshot

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_token
HF_MODEL=Qwen/Qwen2.5-72B-Instruct
SECRET_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

n8n PaperBrain Workflow

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