# Feynman Gate

> 🇨 [中文文档](./README.zh-CN.md)

**An Obsidian plugin that transforms long-form documents into an active, level-by-level learning experience — powered by the Feynman Technique and AI.**

---

## The Problem

AI-generated deep research reports and long markdown files are everywhere. But reading a 10,000-word document from top to bottom rarely leads to genuine understanding. You reach the end, close the tab, and retain maybe 20% of it.

The missing ingredient is **active recall with feedback**. Without being forced to articulate what you've learned, long-form reading stays passive.

---

## What This Plugin Does

Feynman Gate sits alongside your markdown notes and turns reading into a structured, output-first process:

1. **Parses your document** into logical learning units (by heading level).
2. **Guides you step-by-step** — one section at a time, with a visible progress bar.
3. **Challenges you to explain each unit** in your own words, as if teaching it to someone else.
4. **AI judges your explanation** — not just for keywords, but for conceptual understanding — and gives feedback.
5. **Unlocks the next unit** only when you've demonstrated sufficient grasp of the current one.

The result: a reading experience with checkpoints, accountability, and genuine comprehension gates — not just passive scrolling.

---

## Core Features

| Feature | Description |
|---|---|
| 📄 **Smart Parsing** | Automatically segments any markdown file by heading hierarchy |
| 🎯 **Level Selection** | Choose your learning granularity: unit-level or summary-level |
| ✍️ **Feynman Challenges** | Explain each section in your own words before proceeding |
| 🤖 **AI Evaluation** | OpenRouter-compatible LLM assesses conceptual understanding |
| 📊 **Progress Tracking** | Persistent progress bar and session history per file |
| 🔁 **Opt-in per File/Folder** | Right-click any note or folder to enable learning mode |
| 🌐 **Bilingual UI** | Full English / Simplified Chinese interface support |
| 🎨 **Theme-aware** | Automatically follows Obsidian's light/dark theme |

---

## Getting Started

### Installation

> **Note:** This plugin is currently in active development and not yet on the Obsidian community plugin registry.

**Manual Installation:**
1. Download the latest release (`main.js`, `manifest.json`, `styles.css`).
2. Copy the files into your vault at `.obsidian/plugins/feynman-gate/`.
3. In Obsidian: **Settings → Community Plugins → Enable** `Feynman Gate`.

### Configuration

Go to **Settings → Feynman Gate** and set:

- **Provider** — OpenAI, DeepSeek, Qwen, OpenRouter, Moonshot, GLM, Ollama, or custom
- **API Key** — Your own provider API key; the plugin does not provide or pay for API access
- **Base URL** — Filled by the provider preset and editable for any OpenAI-compatible endpoint
- **Model** — The model name from your provider
- **Language** — English or 简体中文

The plugin uses BYOK (bring your own key). Requests go directly from Obsidian to your configured provider, and the key is stored locally in Obsidian plugin data.

### Usage

1. Open any markdown note in your vault.
2. **Right-click the file** in the file explorer → **"Start Feynman Learning"**.
3. Click the **🧠 brain icon** in the document header to open the learning panel.
4. Choose your learning level and begin working through sections.
5. Write your explanation → submit → receive AI feedback → proceed.

---

## Roadmap

- [ ] Multi-agent review with specialized feedback dimensions
- [ ] Embedded quiz generation between sections
- [ ] Spaced repetition scheduling for revisiting weak sections
- [ ] Exportable learning summaries

---

## Tech Stack

- **Framework**: Obsidian Plugin API + TypeScript
- **UI**: React 18
- **LLM**: OpenRouter API (model-agnostic)
- **Persistence**: Obsidian `data.json` via Plugin API

---

## License

MIT