--- slug: "bloom" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/li-evan/bloom@main/README.md" repo: "https://github.com/li-evan/bloom" source_file: "README.md" branch: "main" ---

Bloom

Hire a private AI tutor for anything you want to learn.

Your AI reads how you actually learn โ€” and teaches the next lesson just for you.
Built on Bloom's 2-Sigma research: 1-on-1 tutoring = top 2%.

GitHub stars MIT License Last commit Python 3.11+ Node.js 18+ React 19 FastAPI

๐ŸŒ Website ยท Chinese ยท English

Bloom โ€” from average to the top 2%

--- 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 | Mode | Setup | Best for | |------|-------|----------| | **CLI** | Claude Code + terminal | Power users who like Markdown editors | | **Web** | Browser (React + FastAPI) | Visual learners, shareable setup | Both follow the same flow: **syllabus โ†’ lesson โ†’ annotate โ†’ feedback โ†’ next lesson โ†’ evaluation โ†’ summary**. --- ## Quick Start: CLI Mode Requires only [Claude Code](https://claude.com/claude-code). No backend. ```bash git clone https://github.com/Li-Evan/Bloom.git cd Bloom # Install the tutor skill locally for this clone mkdir -p .claude/skills cp -R skills/bloom-tutor .claude/skills/ claude ``` Then say: `Create a new folder and help me learn [any topic]` **Or install it as a plugin** (bundles `bloom-tutor` plus the `learn-*` skills) โ€” in Claude Code: ```text /plugin marketplace add Li-Evan/Bloom /plugin install bloom@li-evan ``` See [GUIDE.md](https://github.com/li-evan/bloom/blob/HEAD/GUIDE.md) for the full walkthrough. ## Quick Start: Web Mode ### Prerequisites - Python 3.11+ with [uv](https://docs.astral.sh/uv/) - Node.js 18+ - An OpenAI-compatible LLM API key (e.g. [DashScope](https://dashscope.console.aliyun.com/), OpenAI, etc.) ### Setup ```bash 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**, **Source Upload**, or **Project Files**, and start learning. ### Docker ```bash 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 ``` ### Project Files ``` Upload a file / multiple files / a whole folder โ†’ each file renders directly as one page โ†“ Read each file โ†’ highlight text โ†’ ask and get an immediate answer โ†“ No syllabus, no next-lesson generation; the files and highlight Q&A feed next-step recommendations ``` ## Features - **Three course modes** โ€” generate from a topic, upload a PDF/TXT/MD source, or **Project Files** (upload files/a folder, render each directly, highlight-ask anytime, no syllabus or next-lesson generation) - **Learning depth** โ€” choose simple, standard, or deep syllabus expansion when creating a course; shown as a badge on each course card - **Reference material** โ€” paste textbook chapters, papers, or notes when creating a topic course - **Next-topic recommendations** โ€” generate 3 course-ready topics from your full learning history, refresh the set, save ideas to a learning queue, or start one directly through the normal syllabus โ†’ lesson flow - **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 - **Personal center & learning calendar** โ€” open the profile from the header to see a month calendar shaded by daily activity; click any day to see which courses, lessons, and highlights you studied, alongside overview stat cards and a six-month contribution heatmap (streaks and grouping use your local date) ## Skills Bloom ships a set of portable **[Claude Code](https://claude.com/claude-code) skills** in [`skills/`](https://github.com/li-evan/bloom/tree/HEAD/skills/) โ€” self-contained capability packs you can copy into `~/.claude/skills/` (global) or any project's `.claude/skills/` and use anywhere. | Skill | What it does | |-------|-------------| | **bloom-tutor** | The full interactive tutoring system as one skill โ€” syllabus โ†’ adaptive lessons โ†’ `???` annotations โ†’ evaluation โ†’ summary. CLI mode, packaged and portable. | | **learn-deep** | Default deep-dive entry โ€” runs all five lenses below in one pass, then helps you pick a direction | | **learn-crossover** | Learn a new concept by leveraging what you already know (structural analogies) | | **learn-occam** | Decide whether / how deeply something is worth learning (ROI, just-enough) | | **learn-graph** | Build a knowledge-graph map of a field plus a learning path | | **learn-prototype** | Learn by building the crappiest working prototype, then iterating | | **learn-feynman** | Verify true understanding by explaining it back | 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 | Layer | Technology | |-------|-----------| | Backend | Python, FastAPI, SQLAlchemy, SQLite | | Frontend | React, Vite, Tailwind CSS | | AI | Any OpenAI-compatible LLM API | | Container | Docker, docker-compose | | Font | Outfit, JetBrains Mono | ## Commands ```bash 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 ``` โ”œโ”€โ”€ GUIDE.md # CLI usage guide โ”œโ”€โ”€ .env.example # env template โ”œโ”€โ”€ backend/ โ”‚ โ””โ”€โ”€ app/ โ”‚ โ”œโ”€โ”€ courses.py # course, lesson, annotation, feedback, stats, summary APIs โ”‚ โ”œโ”€โ”€ recommendations.py # next-topic recommendation APIs โ”‚ โ”œโ”€โ”€ models.py # Course, Lesson, Annotation, Feedback, Recommendation โ”‚ โ””โ”€โ”€ 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 | Concept | What it means | |---------|--------------| | **Bloom's 2 Sigma** | 1-on-1 tutoring = +2ฯƒ performance over classroom | | **Mastery Learning** | Don't move on until the concept is truly understood | | **Socratic Method** | Ask questions, don't hand answers | | **Spaced Retrieval** | Thought question reviews at lesson start reinforce memory | | **Adaptive Path** | Content adjusts to individual feedback in real-time | ## Star History Star History Chart ## License [MIT](https://github.com/li-evan/bloom/tree/HEAD/LICENSE)