Skip to content

README.md

Latest commit

 

History

History
366 lines (272 loc) · 14.3 KB

README.md

File metadata and controls

366 lines (272 loc) · 14.3 KB

StudyClever

Turn lecture slides into exam-ready study sessions — automatically.

Upload your lecture slides (PPTX/PDF) and past exams, and StudyClever uses AI to generate exam-style questions, schedule them across your study days, and track your progress. Built for students who want to study smarter, not longer.

If this helps you study better, consider giving it a star — it helps other students find it too.

What It Does

  1. Upload lecture slides and past exam papers
  2. Extract slide content and describe images with AI (optional but recommended)
  3. Learn your exam's style — question format, difficulty distribution, distractor patterns
  4. Generate custom MCQs that match your exam's style (standard or hard mode)
  5. Familiarize with slides first — see each slide and answer one question per slide before being quizzed
  6. Schedule questions across your remaining study days with even or easing-in distribution
  7. Study with a daily queue, instant feedback, and progress tracking
  8. Study ahead — pull tomorrow's questions early when you're on a roll

Quick Start

git clone https://github.com/yourusername/studyclever.git
cd studyclever
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env
docker compose up

Open http://localhost:3000 and create an account.

That's it. The database, migrations, and all services start automatically.

Tech Stack

Layer Tech
Frontend Next.js 16, React 19, TypeScript, Tailwind CSS 4
Backend Python, FastAPI
Database PostgreSQL 16
AI Anthropic Claude (Haiku for vision, Sonnet for generation)
Cost Optimization Anthropic Batch API (50% discount, e.g. 1,648 questions for $3.66)
Dev Environment Docker Compose

Features

Guided Setup Wizard

A 6-step wizard walks you through setting up each module:

  1. Upload Slides — drag-and-drop PPTX or PDF lecture files
  2. Upload Past Exams (optional) — past exam papers for style matching
  3. Process Slides (optional, recommended) — AI describes images and enriches slide content so questions cover visual material like diagrams, charts, and formulas. Without enrichment, questions are generated from text only.
  4. Analyze Exam Style (optional) — extracts a style fingerprint from past exams (question format, distractor patterns, difficulty distribution) and injects it into every generated question
  5. Generate Questions — produces exam-style MCQs using Claude Sonnet via the Batch API
  6. Set Up Schedule — configure study days, distribution strategy, and generate the schedule

Question Generation

  • Standard mode — 4 options, single correct answer, classical MCQ
  • Hard mode — 4-6 options, mix of single and multi-answer, number of correct answers hidden
  • Adjustable count — set a target question count, distributed proportionally by slide content length
  • Multi-slide combining — related consecutive slides grouped for cross-slide questions
  • Auto-skip — non-content slides (title pages, table of contents, blank slides) are automatically detected and excluded from generation
  • Per-lecture question decks — regenerate questions for individual lectures without affecting others; switch between deck versions
  • LaTeX support — $...$ inline and $$...$$ display math rendered in questions and options

Two-Phase Study Schedule

The schedule divides all questions into two sequential phases:

Phase 1 — Familiarization:

  • One question per slide, with the slide image visible
  • Ordered linearly within each lecture (continue where you left off)
  • Slides you already familiarized with (even from standalone familiarization) are automatically excluded
  • Helps build context before being quizzed blind

Phase 2 — Quiz:

  • Remaining questions without slide images
  • Questions interleaved across lectures (round-robin)
  • Hard/multi-answer questions presented first within each lecture
  • Questions you already answered correctly (in any context) are excluded

Both phases count toward overall completion. Familiarization is optional — toggle it off in schedule config to jump straight to quizzing.

Distribution Strategies

  • Even — same number of questions every day
  • Ease In — start with fewer questions per day and gradually increase to a sustainable level, helping build the study habit
    • Configurable ramp period (what fraction of days form the ramp)
    • Configurable start intensity (starting rate as fraction of plateau rate)
    • Example: 1,534 questions over 21 days → start at ~10/day, build to ~90/day over 9 days

Schedule Configuration

  • Study days — select which weekdays you study (Mon-Sun toggles)
  • Blackout dates — exclude specific dates (vacations, other exams)
  • Daily question target — optional cap on questions per day
  • Exam date & start date — defines the study window
  • Lecture order — drag-and-drop to customize the order lectures are covered in both familiarization and quiz phases
  • Live preview — shows questions to schedule, already completed count, familiarization/quiz split, and rate projections

Session Chunking

Daily questions are automatically split into bite-sized sessions (default 10 questions, configurable). The dashboard never shows the full daily total — instead you see "Start with 10 questions" and a progress ring scoped to the current session milestone (0/10, then 10/20, then 20/30, etc.). After each session you choose "Next Session" or "Take a Break". The daily load stays invisible so you're never overwhelmed.

Content-Aware Question Timer

An optional per-question countdown timer that adapts to content complexity:

  • Familiarization: timer based on slide content + question + options word count
  • Quiz: timer based on question + options word count only
  • Formula: words × 0.4s + 10s thinking buffer, capped at 15–180 seconds
  • Adjustable speed multiplier (0.5x–2.0x) for personal pace
  • Visual: shrinking bar that shifts blue → amber → red as time runs out
  • Soft mode — when time expires the bar turns red but you can still answer

Study Modes

  • Daily queue — scheduled questions with automatic carry-over for missed days, split into sessions
  • Familiarization (standalone) — browse lectures independently of the schedule
    • Classic mode — see slide, answer question, rate confidence, next slide
    • Read & Recall — browse slides at your own pace, then answer questions from memory without slides visible
  • Study ahead — finished today's queue? Tap "Study Ahead" on the dashboard to get one extra question at a time. Low commitment — answer one, then choose "One More?" or "I'm Done". Questions stay on their scheduled day and just get completed early. When you stop, you get a summary of everything you did that session.
  • Confidence tracking — rate your confidence after each answer (Guessing / Somewhat sure / Confident)
  • Skip — skip questions you can't answer yet; they remain available for later

Progress & Feedback

  • Dashboard — progress ring scoped to next session milestone, module cards with status badges, weekly overview strip
  • Session summaries — accuracy, duration, per-topic breakdowns after each study session
  • Module progress — on track / behind / ahead status with exam countdown
  • Phase tracking — see familiarization and quiz completion separately in schedule summary
  • Question flagging — thumbs up/down on questions; bad-flagged questions excluded from queue
  • Show Slide — reveal the source slide after answering a quiz question
  • Streak tracking — consecutive days of completing all scheduled questions
  • Weak topics — topics with accuracy below 60% highlighted for focused review

Processing Pipeline

PPTX/PDF upload
  -> Slide-by-slide extraction (slide-boundary chunking, never split mid-slide)
  -> Image extraction & AI description (Claude Haiku vision, Batch API)
  -> Enriched markdown (text + image context merged)     [optional]
  -> Exam style fingerprint from past exams               [optional]
  -> MCQ generation with style injection (Claude Sonnet, Batch API)
  -> Two-phase schedule: familiarization first, then quiz
  -> Daily study queue with automatic rollover

Real-Time Events

  • SSE streaming — processing progress updates pushed to the UI in real-time
  • Batch job monitoring — view status of AI generation jobs (pending, processing, complete, failed)
  • Background polling — batch poller runs on startup, resumes incomplete jobs automatically

Setup

With Docker (recommended)

Prerequisites: Docker and Docker Compose

cp .env.example .env

Edit .env and set your ANTHROPIC_API_KEY (get one here).

docker compose up
Service URL
Frontend http://localhost:3000
Backend API http://localhost:8000
API Docs http://localhost:8000/docs
PostgreSQL localhost:5432

Hot reload is enabled for both frontend and backend. Edit files in frontend/src/ or backend/app/ and changes reflect automatically.

Without Docker

Prerequisites: Node.js 20+, Python 3.11+, PostgreSQL 16

Backend:

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Set NEXT_PUBLIC_API_URL=http://localhost:8000 in frontend/.env.local when running standalone.

Environment Variables

Copy .env.example to .env and configure:

Variable Required Default Description
ANTHROPIC_API_KEY Yes — Your Anthropic API key
POSTGRES_USER No postgres Database user
POSTGRES_PASSWORD No postgres Database password
POSTGRES_DB No studyclever Database name
SECRET_KEY No change-me-in-production JWT signing key
DATABASE_URL No auto-generated Full PostgreSQL connection string

LLM Tuning (optional)

Variable Default Description
IMAGE_DESCRIPTION_MODEL claude-haiku-4-5-20251001 Model for image descriptions
MCQ_GENERATION_MODEL claude-sonnet-4-6 Model for question generation
MCQ_QUESTIONS_PER_SLIDE 4 Default exam questions per slide
FAMILIARIZATION_QUESTIONS_PER_SLIDE 2 Familiarization questions per slide

Project Structure

studyclever/
├── frontend/                   # Next.js app
│   ├── src/
│   │   ├── app/               # Pages (auth, modules, study, queue, familiarize)
│   │   ├── components/        # React components
│   │   │   ├── study/        # QuestionCard, StudySession, FamiliarizationSession
│   │   │   ├── schedule/     # ScheduleConfigForm, ScheduleCalendar, LectureOrderEditor
│   │   │   ├── dashboard/    # DailyProgressRing, ModuleCard, WeekStrip
│   │   │   └── setup/        # SetupWizard, SetupStep
│   │   └── lib/              # API client, hooks, auth context
│   └── Dockerfile
├── backend/                    # FastAPI app
│   ├── app/
│   │   ├── main.py           # Entry point & lifespan
│   │   ├── api/routes/       # REST endpoints
│   │   ├── models/           # SQLAlchemy models
│   │   ├── schemas/          # Pydantic request/response schemas
│   │   ├── services/         # Business logic (generation, scheduling, queue)
│   │   └── core/            # Config & settings
│   ├── alembic/             # Database migrations
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
├── LICENSE
└── README.md

API

Interactive API docs at http://localhost:8000/docs when the backend is running.

Area Key Endpoints
Auth POST /api/auth/register, POST /api/auth/login
Modules POST /api/modules, GET /api/modules/{id}
Upload POST /api/files/upload
Processing POST /api/modules/{id}/enrich, POST /api/modules/{id}/extract-style
Generation POST /api/modules/{id}/generate-questions
Schedule Config POST /api/modules/{id}/schedule-config, PUT .../schedule-config
Schedule POST /api/modules/{id}/generate-schedule, GET .../schedule
Study Queue GET /api/queue, POST /api/queue/answer, POST /api/queue/pull-ahead
Familiarization GET /api/lectures/{id}/familiarize, POST /api/questions/{id}/familiarize-answer
Progress GET /api/modules/{id}/progress, GET /api/progress
Lecture Order PUT /api/modules/{id}/lectures/reorder
Flags POST /api/questions/{id}/flag, DELETE /api/questions/{id}/flag
Regeneration POST /api/lectures/{id}/regenerate, GET /api/lectures/{id}/decks

Database Migrations

Migrations run automatically on Docker startup. For manual use:

cd backend

# Apply all migrations
alembic upgrade head

# Create a new migration after model changes
alembic revision --autogenerate -m "describe your change"

# Roll back one step
alembic downgrade -1

Development

# Frontend linting
cd frontend && npm run lint

# Backend — run with reload
cd backend && uvicorn app.main:app --reload

Deployment Checklist

  • Set a strong SECRET_KEY
  • Set ENV=production
  • Use proper PostgreSQL credentials
  • Configure NEXT_PUBLIC_API_URL for your domain
  • Enable HTTPS
  • Set up database backups

Troubleshooting

Docker won't start?

docker compose down -v && docker compose up

Database errors? Check that PostgreSQL is healthy:

docker compose logs postgres

Generation not working? Verify your API key:

grep ANTHROPIC_API_KEY .env

Port in use?

lsof -i :3000  # or :8000

License

This project is licensed under CC BY-NC 4.0 — you're free to use, share, and adapt it for personal and educational purposes. You must give credit to StudyClever and link to this repository. Commercial use is not permitted. See LICENSE for full terms.

Found a bug? Have a feature idea? Open an issue — contributions that make studying better for everyone are always welcome.