Bloom

Your Personal AI Tutor — Powered by the 2-Sigma Method

From average to top 2%. One lesson at a time.

🌐 Website · Chinese · English

In 1984, educational psychologist Benjamin Bloom discovered that students receiving one-on-one tutoring scored 2 standard deviations (+2σ) above the classroom average — jumping to the top 2%. Bloom called this the "2 Sigma Problem": the effect is proven, but personal tutors don't scale.

Bloom solves this with AI. It generates a structured syllabus, delivers lessons one at a time, reads your annotations and feedback, then tailors the next lesson to your exact understanding level — just like a real tutor would.

Two Ways to Use

Both follow the same flow: syllabus → lesson → annotate → feedback → next lesson → evaluation → summary.

Quick Start: CLI Mode

Requires only Claude Code. No backend.

git clone https://github.com/Li-Evan/Bloom.git
cd Bloom
claude

Then say: Create a new folder and help me learn [any topic]

See GUIDE.md for the full walkthrough.

Quick Start: Web Mode

Prerequisites

• Python 3.11+ with uv
• Node.js 18+
• An OpenAI-compatible LLM API key (e.g. DashScope, OpenAI, etc.)

Setup

git clone https://github.com/Li-Evan/Bloom.git
cd Bloom

# Configure
cp .env.example .env
# Edit .env — fill in LLM_API_KEY

# Backend
cd backend && uv sync && uv run uvicorn app.main:app --reload --port 8000

# Frontend (new terminal)
cd frontend && npm install && npm run dev

Open http://localhost:5173. Click New Course, choose Topic or Source Upload, and start learning.

Docker

cp .env.example .env   # fill in API key
docker compose up -d   # visit http://localhost:3000

How It Works

Topic Mode

Create course → AI generates syllabus + lesson 01
                        ↓
        Read lesson → highlight text → add annotations
                        ↓
        Write feedback → answer thought questions
                        ↓
        Click "Done Reading" → AI generates next lesson
        (answer review + annotation responses + new content)
                        ↓
        Repeat until all mastery items checked ✅
                        ↓
        Auto-generate evaluation → then summary

Source Mode

Upload PDF / TXT / MD → AI generates syllabus + source-reading chapter
                          ↓
       Read source → highlight text → ask and get an immediate answer
                          ↓
       Click "Done Reading" → AI reads the full source + Q&A, then generates the next lesson
                          ↓
       Continue with the normal adaptive lesson flow

Features

• Two course modes — generate from a topic, or upload a PDF/TXT/MD source
• Reference material — paste textbook chapters, papers, or notes when creating a topic course
• Highlight Q&A sessions — select any text in any lesson (or source) and a small icon pops up; click it to ask. The highlighted text stays marked in yellow, the AI answers instantly, and you can keep asking follow-ups in the same thread. The window is draggable and collapses into a margin dot you can reopen anytime. Each session sees the full lesson + the highlighted span + its own conversation, and your questions still feed the next lesson.
• Adaptive lessons — each lesson addresses your specific gaps from the previous one
• Chapter sidebar — quick-jump between lessons while reading
• Collapsible syllabus — track mastery progress without clutter
• Streaming generation — watch AI write the next lesson in real-time

Skills

Bloom ships a set of portable Claude Code skills in skills/ — self-contained capability packs you can copy into ~/.claude/skills/ (global) or any project's .claude/skills/ and use anywhere.

Each folder is dependency-free: copy it into a skills directory, then just talk to Claude Code (e.g. "help me learn X", "I'm done reading").

Tech Stack

Commands

make dev-backend      # backend with hot reload
make dev-frontend     # frontend dev server
make test             # run pytest
make up / make down   # docker start / stop

Project Structure

├── Claude.md              # AI tutor instructions (CLI mode)
├── GUIDE.md               # CLI usage guide
├── .env.example           # env template
├── backend/
│   └── app/
│       ├── courses.py     # all API routes + AI prompt logic
│       ├── models.py      # Course, Lesson, Annotation, Feedback
│       └── config.py      # reads .env
├── frontend/
│   └── src/pages/
│       ├── DashboardPage  # course list + create form
│       ├── CoursePage     # syllabus + lesson list
│       └── LessonPage     # reader + annotations + feedback + AI gen
├── example/               # pre-built topics for CLI mode
├── site/                  # marketing website (standalone Astro static build, decoupled from the app)
└── skills/                # portable Claude Code skills (bloom-tutor + learn-*)

The Science

License

MIT