README.md

---
title: StudyHub
emoji: 📚
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
---

# StudyHub

A private, multilingual (Italian + English) study assistant for a small group of
verified classmates. It answers questions, writes summaries, and generates quizzes
**grounded in your course materials**, citing the **exact file + slide/page** so
answers can be fact-checked at the source.

- **Grounded + cited:** every claim maps to a closed-set source id rendered from
  trusted retrieval metadata — a citation can't point at the wrong place.
- **Cross-file topic gathering** via a lightweight concept index.
- **Open-source models**, **free** to run: a free Hugging Face Space + open LLMs
  served by Groq (→ Cerebras failover). Short retrieved snippets are sent to a
  no-training provider to generate answers; original files stay in a private dataset.
- **Verified access only:** the whole app is gated by a salted-hash login.

## How it fits together

```
offline ingestion (this repo's CLI)            free HF Space (this app)
materials → clean text + exact anchors         pull index from private dataset
        → chunks → concept index → FAISS   ──►  retrieve + cite + Groq/Cerebras
        → upload to PRIVATE dataset             gated by login; serve downloads
```

## Status (Phase 1)

**Working now:** gated login · ask questions · summaries · quizzes (all grounded, cited, **Italian + English**) · **open/download the exact cited source** next to each answer · cross-file topic gathering · **tamper-proof citations** (the model can only cite retrieved snippets; the file + slide/page label is rendered from trusted metadata, so it can't point at the wrong place).

**Deferred to Phase 2/3 (not built yet):** answers from **web/online sources**; **OCR** for scanned/handwritten materials (digital docs work today — image-only pages are detected and skipped); **in-app uploads** by classmates (the owner adds materials via the dataset + GitHub Action); a richer concept *graph*; **page-level deep-links** in citations (today you open the cited file and go to the stated slide/page yourself). Materials are normalized to clean text (not literal `.md` files).

See **docs/DEPLOY.md** for the step-by-step deployment guide, and
`docs/superpowers/specs/2026-06-09-studyhub-design.md` for the full design.

> Materials and secrets are **never** in this repo: originals live in a private
> Hugging Face dataset; tokens/keys/users live in Space Secrets.