| --- |
| title: PaperProf |
| emoji: 📄 |
| colorFrom: purple |
| colorTo: blue |
| sdk: gradio |
| sdk_version: 6.16.0 |
| python_version: '3.12' |
| app_file: app.py |
| pinned: false |
| tags: |
| - track:backyard |
| - sponsor:openbmb |
| - achievement:offgrid |
| - achievement:welltuned |
| - achievement:offbrand |
| - achievement:llama |
| - achievement:sharing |
| - achievement:fieldnotes |
| --- |
| |
| Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference |
|
|
| --- |
|
|
| # PaperProf — AI Study Buddy |
|
|
| ## Demo |
|
|
| Video walkthrough: https://youtu.be/eyoXrGMjXWc |
|
|
| LinkedIn post: https://www.linkedin.com/posts/ryad-gazenay_buildsmallhackathon-huggingface-gradio-ugcPost-7471900513991729152-Th-Y/ |
| |
| ## Models used |
| |
| - [build-small-hackathon/MiniCPM4-8B-PaperProf](https://huggingface.co/build-small-hackathon/MiniCPM4-8B-PaperProf) — QLoRA fine-tune of openbmb/MiniCPM4-8B on SQuAD, used for question generation and answer evaluation |
| - [black-forest-labs/FLUX.1-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell) — FLUX.2-klein-4B, used for session image generation |
| |
| ## Sponsor prize categories |
| |
| - OpenBMB (MiniCPM4.1-8B) |
| - Black Forest Labs (FLUX.2-klein-4B) |
| |
| PaperProf turns any course PDF into an interactive study session. |
| Upload your lecture notes or textbook, receive auto-generated questions drawn |
| directly from the material, type your answers, and get instant, constructive |
| feedback powered by a local LLM (MiniCPM4-8B). |
| |
| --- |
| |
| ## How it works |
| |
| ``` |
| PDF upload |
| └─► core/parser.py — extract raw text with PyMuPDF |
| └─► core/chunker.py — split text into thematic chunks |
| └─► core/questioner.py — LLM generates a question from a chunk |
| └─► student answers |
| └─► core/evaluator.py — LLM evaluates & explains |
| ``` |
| |
| The LLM (loaded once at startup via `model/llm.py`) handles both question |
| generation and answer evaluation. Everything runs locally — no API keys needed. |
| |
| --- |
| |
| ## File structure |
| |
| ``` |
| PaperProf/ |
| ├── app.py # Gradio UI — entry point |
| ├── requirements.txt # Python dependencies |
| ├── README.md # This file |
| ├── core/ |
| │ ├── __init__.py |
| │ ├── parser.py # PDF → plain text (PyMuPDF) |
| │ ├── chunker.py # plain text → thematic chunks |
| │ ├── questioner.py # chunk → study question (LLM) |
| │ └── evaluator.py # (question, chunk, answer) → feedback (LLM) |
| └── model/ |
| ├── __init__.py |
| └── llm.py # singleton LLM wrapper (MiniCPM4-8B / Transformers) |
| ``` |
| |
| ### File roles |
| |
| | File | Role | |
| |---|---| |
| | `app.py` | Builds the Gradio interface and wires the pipeline together. | |
| | `core/parser.py` | Opens the PDF with PyMuPDF (`fitz`) and extracts plain text page by page. | |
| | `core/chunker.py` | Splits the raw text on paragraph boundaries, merging short paragraphs and capping chunk size so the LLM isn't overloaded. | |
| | `core/questioner.py` | Sends a chunk to the LLM with a professor-style prompt and returns one open-ended question. | |
| | `core/evaluator.py` | Sends the question, source chunk, and student answer to the LLM, which returns a structured verdict + model answer. | |
| | `model/llm.py` | Loads `openbmb/MiniCPM4-8B` once via Transformers, exposes a `generate(prompt)` method, and caches the instance as a singleton. | |
| | `requirements.txt` | Pins all Python dependencies needed to run the project. | |
| |
| --- |
| |
| ## Setup |
| |
| ```bash |
| # 1. Create a virtual environment |
| python -m venv venv |
| source venv/bin/activate # Windows: venv\Scripts\activate |
| |
| # 2. Install dependencies |
| pip install -r requirements.txt |
| |
| # 3. (Optional) override the model or device |
| export PAPERPROF_MODEL="openbmb/MiniCPM3-4B" # smaller model for testing |
| export PAPERPROF_DEVICE="cuda" # cuda | mps | cpu | auto |
| |
| # 4. Launch |
| python app.py |
| ``` |
| |
| The Gradio app will open at `http://localhost:7860`. |
| |
| --- |
| |
| ## Usage |
| |
| 1. Click **Upload course PDF** and choose your file. |
| 2. Click **Load PDF** — PaperProf parses the document and reports how many |
| chunks were found. |
| 3. Click **New Question** to get a question generated from a random chunk. |
| 4. Type your answer in the **Your Answer** box. |
| 5. Click **Submit Answer** to receive structured feedback. |
| |
| Repeat steps 3–5 as many times as you like to practice the full material. |
| |
| --- |
| |
| ## Requirements |
| |
| - Python ≥ 3.10 |
| - A GPU with ≥ 10 GB VRAM is recommended for MiniCPM4-8B in bfloat16. |
| CPU inference works but is slow; set `PAPERPROF_MODEL` to a 4B variant for |
| faster CPU runs. |
|
|
