Smart Study Agent

SmartStudy Agent

> The AI study agent that learns how you learn — a reinforcement-learning policy decides what you study next, an FSRS memory model decides when you review it, and an LLM generates the quizzes in between. In your browser, in your terminal, or inside Claude via MCP.

[](https://www.python.org/downloads/) [](https://www.anthropic.com/) [](https://streamlit.io/) [-4A90E2.svg)](chrome-extension/) [](https://github.com/open-spaced-repetition/py-fsrs) [](ankiexport.py) [](mcpserver.py) [](LICENSE) [](https://huggingface.co/spaces/HumphreySun98/smart-study-agent)

[English](#-live--two-ways-to-use-it) · [中文简介](#-中文简介) · [📚 Technical Deep Dive](docs/DEEP_DIVE.md) — the POMDP framing, the math behind both policies, and the experiments (including the ones the heuristic won)

🌐 Live — Two Ways to Use It

| | Where it runs | How to try it | |---|---|---| | Web app | Hugging Face Spaces (free Kimi-K2 backend) | Open in browser | | Chrome extension | Your browser — works on any page, PDF, or YouTube video | Install from the Chrome Web Store · [Source](chrome-extension/) (MV3) |

Live on the Chrome Web Store — click to install.

Side panel running on a YouTube ML course — topics auto-extracted from captions, belief state updating in real time.

The web app runs on Hugging Face Spaces using free HF Inference Providers (Kimi-K2). The Chrome extension calls the Anthropic API directly from your browser — same agent core, zero backend. For local development, plug in your own Anthropic key to get Claude's higher-quality reasoning.

SmartStudy Agent is a goal-based, partially observable AI agent that turns any lecture material into a fully personalized learning experience. Unlike a chatbot, it maintains a persistent belief state about student knowledge and uses an adaptive policy to decide what to study next.

---

Why SmartStudy?

Traditional study tools are static. They show you the same content regardless of what you already know. SmartStudy Agent solves this by closing the loop:

| Problem | SmartStudy's Solution | |---------|----------------------| | Generic study materials | Topics extracted and prioritized per student | | No feedback on weak areas | Quiz answers update a persistent belief state | | Same recommendations for everyone | Q-learning policy (or Contextual Bandit) adapts per student trajectory | | Forgetting without practice | FSRS spaced repetition — the same modern memory model family as Anki (SM-2 fallback) | | Out-of-order topics | Topological sort over a concept dependency graph | | Locked into one app | Anki .apkg export, MCP server for Claude, Chrome extension, web app |

How it compares

| | SmartStudy | DeepTutor | OpenTutor | Anki | |---|---|---|---|---| | Runs where you read (browser extension) | ✅ Chrome Web Store | ❌ web workspace | ❌ self-hosted app | ❌ | | RL policy decides next action | ✅ Q-learning + LinUCB, honest benchmark | ❌ | ❌ | ❌ | | Spaced repetition | ✅ FSRS | ❌ | ✅ FSRS | ✅ FSRS | | Quiz generation from any material | ✅ | ✅ | ✅ | ❌ | | Anki export | ✅ .apkg | ❌ | ❌ | — | | Drive it from Claude (MCP) | ✅ | ❌ | ❌ | via 3rd-party | | Footprint | ~3k LOC, SQLite, runs on free tier | Full platform (FastAPI + Next.js) | FastAPI + Next.js | Desktop app |

SmartStudy is deliberately not an all-in-one learning platform — it's the lightweight agent core: observe → plan → quiz → evaluate → adapt, with real learning-science scheduling. If you want a full workspace, DeepTutor is excellent. If you want the decision loop embedded where you already study — this repo.

---

Architecture

SmartStudy implements the OPEAA loop — a five-phase adaptive agent cycle:

       ┌─────────────────────────────────────────────────┐
       │              Lecture Materials                  │
       │   PDF · TXT · MD · DOCX · PPTX · VTT · SRT      │
       └────────────────────┬────────────────────────────┘
                            ▼
       ┌─────────────────────────────────────────────────┐
       │     Claude API  ·  claude-opus-4-6              │
       │     thinking: { type: "adaptive" }              │
       └────────────────────┬────────────────────────────┘
                            ▼
       ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐
       │ OBSERVE │─▶│  PLAN   │─▶│   ACT   │─▶│ EVALUATE│
       │         │  │  + DAG  │  │  quizzes│  │  + LLM  │
       │ extract │  │   sort  │  │  3 MCQs │  │feedback │
       │ topics  │  │         │  │         │  │         │
       └─────────┘  └─────────┘  └─────────┘  └────┬────┘
            ▲                                       │
            │           ┌──────────────────────────▼┐
            │           │           ADAPT           │
            └───────────┤  Heuristic OR Q-learning  │
                        │  StudentProfile updated   │
                        └─────────┬─────────────────┘
                                  ▼
                  ┌─────────────────────────────────┐
                  │   Persistent Belief State       │
                  │   (JSON storage · per student)  │
                  └─────────────────────────────────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
          Spaced Repetition  Concept Graph    Interfaces
            (FSRS)           (DAG topo sort)  Streamlit · Chrome ext
                                              MCP server · Agent Skill

The agent is modeled as a POMDP (partially observable Markov decision process):

• State — student's true knowledge (hidden)
• Belief state — StudentProfile (mastered topics, weak areas, quiz history)
• Actions — advance · reinforce · review
• Observations — student answers to generated quizzes
• Reward — improvement in quiz scores over time

---

Features

Core Agent

• 5-phase OPEAA loop — Observe → Plan → Act → Evaluate → Adapt
• Claude integration with thinking: {type: "adaptive"} for internal reasoning
• Goal-based agent design following Russell & Norvig's PEAS framework
• POMDP belief state persisted across sessions
• Two adaptive policies — heuristic (Bloom's 70% mastery threshold) and tabular Q-learning

Knowledge & Memory

• Concept dependency graph — Kahn's algorithm topological sort over a topic prerequisite DAG, rendered as an interactive draggable graph (pyvis)
• FSRS spaced repetition — per-topic memory model (stability · difficulty · recall probability) via py-fsrs; automatic SM-2 fallback
• Anki export — one click turns your generated quiz bank into a styled .apkg deck
• Persistent SQLite storage — student profiles survive across sessions
• Multi-student support with peer comparison dashboard

Integrations

• MCP server — Claude Desktop / Claude Code can query your review queue, generate quizzes, record results (training the RL policy), and export decks
• Claude Agent Skill — skills/smartstudy/ turns any Claude Code session into an adaptive study coach
• Multi-provider LLM — Claude, HF Inference, or any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, DeepSeek) — fully local studying is supported

Input & Evaluation

• 7 input formats — PDF, TXT, MD, DOCX, PPTX, VTT, SRT
• Quantitative evaluation — Monte Carlo simulation of adaptive vs random baselines
• Mock client — MockAnthropic lets you run the entire system offline without an API key

User Interface

• Streamlit web app with 8 pages (premium glassmorphism theme)
• Chrome extension (MV3) — run the full OPEAA loop on any web page, Q-table persisted in chrome.storage.local
• Interactive terminal UI powered by rich
• Auto-demo mode for video recording

---

Installation

git clone https://github.com/HumphreySun98/Smart-Study-Agent.git
cd Smart-Study-Agent
pip install -r requirements.txt

The agent supports four LLM backends and picks one automatically:

| Backend | Env variable | Cost | Quality | |---------|--------------|------|---------| | Anthropic Claude | ANTHROPIC_API_KEY | Pay as you go | ⭐⭐⭐⭐⭐ Best — supports adaptive thinking | | Any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, DeepSeek…) | SMARTSTUDY_LLM_BASE_URL + SMARTSTUDY_LLM_MODEL | Free if local | ⭐⭐⭐–⭐⭐⭐⭐ your choice | | HF Inference (Kimi-K2) | HF_TOKEN | Free | ⭐⭐⭐⭐ Great | | Mock | (no env vars) | Free | ⭐⭐ Canned responses for offline demos |

# Option 1 — Claude (premium quality)
export ANTHROPIC_API_KEY=sk-ant-...

# Option 2 — fully local & private with Ollama
export SMARTSTUDY_LLM_BASE_URL=ollama        # shortcut for http://localhost:11434/v1
export SMARTSTUDY_LLM_MODEL=llama3.1

# ...or any other OpenAI-compatible server
export SMARTSTUDY_LLM_BASE_URL=https://api.deepseek.com/v1
export SMARTSTUDY_LLM_MODEL=deepseek-chat
export SMARTSTUDY_LLM_API_KEY=sk-...

# Option 3 — Hugging Face (completely free)
export HF_TOKEN=hf_...

# Option 4 — Mock mode (no setup)
# just run the agent without any keys

Get a Claude key from console.anthropic.com ($5 free credit) or a free HF token from huggingface.co/settings/tokens.

---

Quick Start

Hosted Demo (zero install)

👉 https://huggingface.co/spaces/HumphreySun98/smart-study-agent

Web App (local)

streamlit run app.py

Open http://localhost:8501, create a student in the sidebar, then go to 📖 Study Session to run the full OPEAA loop on a sample ML lecture or your own PDF.

Terminal demo (interactive)

python demo.py
python demo.py --pdf path/to/lecture.pdf
python demo.py --mock                  # offline mode, no API key needed

Auto demo (for screen recording)

python demo_auto.py

Chrome extension (run the agent on any web page, PDF, or YouTube video)

Now live on the Chrome Web Store — install in one click.

Prefer to run the source directly? Load it unpacked in ['Linear Algebra', 'Neural Networks', 'Backpropagation']

Spaced repetition scheduler (SM-2)

duetoday = getreviewqueue(record["quizhistory"])

Q-learning adaptive policy

policy = QLearningPolicy() action = policy.chooseaction(score=0.55) # 'reinforce' policy.update(prevscore=0.55, action=action, new_score=0.80)

Quantitative evaluation vs random baseline

results = compare(nruns=30, nsessions=20) print(f"Adaptive beats baseline by {results['improvement_pct']:.1f}%")

---

## Web App Pages

| Page | Purpose |
|------|---------|
| 🏠 **Dashboard** | Mastered topics, weak areas, due reviews, and key metrics |
| 📖 **Study Session** | Upload a lecture and run the full OPEAA loop step-by-step |
| 🔁 **Spaced Review** | FSRS memory state per topic — recall %, stability, next due date |
| 🃏 **Anki Export** | Build a styled `.apkg` deck from your generated question bank |
| 🧠 **Concept Graph** | Interactive draggable prerequisite DAG — mastered/weak topics color-coded |
| 📊 **Progress History** | Personal score trajectory across all attempts |
| 👥 **Peer Comparison** | Multi-student leaderboard ranked by average score |
| 🎯 **RL Policy** | Inspect the Q-table and train it on simulated episodes |
| 🧪 **Baseline Evaluation** | Adaptive vs random topic-selection simulation results |
| 📋 **Pilot Study** | Real usage metrics, engagement analysis, learning progression report |

---

## Project Structure

smartstudy-agent/ ├── smartstudyagent.py # Core agent — 5 OPEAA phases ├── mockclaude.py # Offline mock client ├── hfclient.py # Hugging Face Inference adapter (free LLM backend) ├── app.py # Streamlit web app (8 pages) ├── demo.py # Interactive terminal demo ├── demoauto.py # Automated demo (no input needed) │ ├── storage.py # SQLite persistent storage (+ question bank) ├── conceptgraph.py # Topic prerequisite DAG with cross-course linking ├── pilotstudy.py # Pilot study data collection and analysis ├── rlpolicy.py # Tabular Q-learning policy ├── banditpolicy.py # Contextual Bandit (LinUCB) — alternative to RL ├── spacedrepetition.py # FSRS review scheduler (SM-2 fallback) ├── ankiexport.py # Question bank → Anki .apkg deck (genanki) ├── mcpserver.py # MCP server — drive the agent from Claude ├── skills/smartstudy/ # Claude Agent Skill — study coach for Claude Code ├── multiformat.py # PDF/TXT/MD/DOCX/PPTX/VTT/SRT loader ├── evaluation.py # Adaptive vs baseline simulation ├── experiments/ # Reproducible studies (scheduler comparison, ...) ├── docs/DEEPDIVE.md # POMDP framing, policy math, experiment analysis │ ├── generatevisuals.py # Generates architecture diagrams ├── requirements.txt # Python dependencies ├── README.md # This file │ ├── chrome-extension/ # Chrome MV3 extension — OPEAA loop in the browser │ ├── manifest.json │ ├── popup.{html,css,js} # Gradient popup UI + full agent logic │ ├── content.js # Active-tab text extractor │ ├── options.{html,js} # API key + model settings │ ├── background.js # Service worker │ └── icons/ # 16/48/128 PNG │ ├── data/ # Created at runtime │ ├── smartstudy.db # SQLite database (student profiles + sessions) │ ├── qtable.json # Q-learning policy state │ └── conceptgraph.json # User-defined graph edges │ └── visuals/ # Generated PNG diagrams ├── adaptiveloop.png ├── systemarchitecture.png ├── performancedashboard.png └── ai_techniques.png

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| LLM | Claude (adaptive thinking) · any OpenAI-compatible endpoint · HF Inference |
| Web UI | Streamlit |
| RL | Tabular Q-learning over discretized score buckets + LinUCB bandit |
| Knowledge Graph | NetworkX + Kahn's algorithm + pyvis (interactive) |
| Spaced Repetition | FSRS via [py-fsrs](https://github.com/open-spaced-repetition/py-fsrs) (SM-2 fallback) |
| Flashcards | genanki → Anki `.apkg` |
| Agent Interop | MCP server (FastMCP) + Claude Agent Skill |
| Storage | SQLite (auto-migrates from JSON, scales to >1k students) |
| Document Parsing | pypdf, python-docx, python-pptx |
| Terminal UI | rich |

---

## How the Agent Decides

The ADAPT phase uses a **two-layer decision system**: the RL policy chooses the action, and the LLM explains the decision to the student in natural language.

### Q-Learning Policy (decides the action)

The action (`advance` / `reinforce` / `review`) is chosen by a tabular Q-learning agent — **not** by the LLM. This runs every time a student finishes a quiz.

| Component | Value |
|-----------|-------|
| **State** | Quiz score discretized into 5 buckets: `very_low` / `low` / `medium` / `high` / `very_high` |
| **Actions** | `review` · `reinforce` · `advance` |
| **Reward** | Score change between attempts: `r = (new_score − prev_score) × 10` |
| **Learning rate (α)** | 0.2 |
| **Discount factor (γ)** | 0.8 |
| **Exploration (ε)** | 0.15 (epsilon-greedy) |

Update rule:

Q(s, a) ← Q(s, a) + α · [r + γ · max(Q(s', a')) − Q(s, a)]

The Q-table is **persisted to disk** (`data/qtable.json`) and trains on every real quiz attempt. It can also be inspected and manually trained in the **🎯 RL Policy** page.

### LLM Layer (explains the decision)

After

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [HumphreySun98](https://github.com/HumphreySun98)
- **Source:** [HumphreySun98/Smart-Study-Agent](https://github.com/HumphreySun98/Smart-Study-Agent)
- **License:** MIT
- **Homepage:** https://huggingface.co/spaces/HumphreySun98/smart-study-agent

Install and usage instructions live in the source repository linked above.