<div align="center">

# Nonlinear Learner

**任务驱动的非线性学习导师 | Task-Driven Nonlinear Learning Tutor**

先了解你的背景和任务，从你提出的知识点出发，拆开整个领域所需的知识

Understand your background and task, unpack the knowledge you need from your starting point

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![Tests: 137](https://img.shields.io/badge/Tests-137%20passed-brightgreen.svg)](#tests)

</div>

---

## 核心理念 | Core Philosophy

传统学习工具假设你有一张完整的知识地图，然后规划从 A 到 B 的路径。但现实中，当你对一个领域一无所知或只有片面了解时，你往往是从**一个具体的小知识点**出发的——一篇文章里看到的一个术语、一个项目里用到的一个概念。

**Nonlinear Learner** 先了解你的背景和任务，从你提出的那个点出发，非线性地把完成任务所需的知识"拆开"：

- **非线性离散**：可以跳跃到任务需要的任意知识点，不按拓扑顺序
- **逻辑保证**：每次跳跃都说明为什么，知识点之间有清晰关联
- **应用导向**：优先学能立即用于完成任务的知识，跳过暂时用不到的
- **背景感知**：根据你的背景跳过已知的，补充缺失的

Traditional tools plan A-to-B paths on a complete map. But in reality, you start from **one small concept**. This tool understands your background and task, then **unpacks** the knowledge you need — non-linearly but logically, application-oriented.

```
用户: "我想用 React 做仪表盘，会 HTML/CSS，看到别人用 useEffect"
                              │
                    ┌─────────▼──────────┐
                    │  导师拆解知识轨迹     │
                    └─────────┬──────────┘
                              │
  [1] 组件 ← 你看到的 useEffect 就在组件里
       │
  [2] JSX ← 组件用 JSX 写（跳到这里因为你不了解）
       │
  [3] useEffect ← 回到你的起始点，现在理解了上下文
       │
  [4] useState ← 仪表盘需要交互状态（跳跃，但应用需要）
       │
  [5] 数据获取 ← 仪表盘要从 API 拉数据（跳跃，任务驱动）
       │
  [6] 列表渲染 ← 展示多个数据卡片
       │
  ✗ 不学 Redux（暂时不需要）  ✗ 不学 SSR（任务用不到）
```

---

## ✨ 特性 | Features

| 中文 | English |
|------|---------|
| **任务驱动导师**：先问背景和任务，再拆解知识 | **Task-driven tutor**: ask background first, then unpack |
| 非线性跳跃，但每步有逻辑关联 | Non-linear jumps with logical connections |
| 应用导向，跳过暂时用不到的 | Application-oriented, skip unnecessary |
| 对话式交互，可提问/跳过/调整 | Conversational, ask/skip/adjust anytime |
| MCP Server，接入 Claude/Cursor | MCP Server for AI tool integration |
| 辐射式探索 + 路径规划两种补充模式 | Radiative exploration + path planning modes |
| SQLite 持久化，进度自动保存 | SQLite persistence, auto-save |

---

## 🚀 快速开始 | Quick Start

### 1. 安装 | Install

```bash
pip install -e .
```

### 2. 一键配置 | One-Click Setup

```bash
nonlinear-learner setup
```

### 3. 对话式导师（核心功能） | Guided Tutor (Core)

```bash
nonlinear-learner guide
```

导师会引导你完成三步：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  对话式学习导师 | Guided Learning
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

第一步：告诉我你的学习目标
例如：用 React 做一个仪表盘、理解 Transformer 原理
> 用 React 做一个数据仪表盘

第二步：告诉我你的知识背景
例如：会 HTML/CSS 和一些 JS
> 会 HTML/CSS，JS 基础薄弱

第三步：你从哪里开始？
你看到了什么、遇到了什么、对什么好奇？
> 看到别人代码里有 useEffect，不懂是什么

正在拆解知识...
✓ 学习轨迹已生成（6 个知识点）

领域概述: React 是用于构建用户界面的库...

学习轨迹:
  → [1] 组件 (难度3/5)
       你看到的 useEffect 就在组件内部使用
    [2] JSX (难度2/5) ← 组件
       组件用 JSX 语法编写，需要先理解
    [3] useEffect (难度3/5) ← 组件, JSX
       回到你的起始点，现在有了上下文
    [4] useState (难度3/5) ← useEffect
       仪表盘需要交互状态
    [5] 数据获取 (难度3/5) ← useEffect
       仪表盘需要从 API 拉数据
    [6] 列表渲染 (难度2/5) ← useState
       展示多个数据卡片

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  步骤 1/6: 组件
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  📌 React 组件是可复用的 UI 单元
  ❓ 为什么学: 你看到的 useEffect 就在组件内部
  🔗 关联: 起始点
  ⏱  预计 30 分钟

  [AI 生成结合你任务的讲解...]

>>> next    ← 继续下一步
>>> ask     ← 提问（系统会调整轨迹）
>>> skip    ← 跳过这步
>>> info    ← 查看完整轨迹
>>> quit    ← 退出保存
```

---

## 📖 使用方式 | Usage

### CLI 命令 | CLI Commands

| 命令 | 说明 | Description |
|------|------|-------------|
| **`guide`** | **任务驱动导师（核心）** | **Task-driven tutor (core)** |
| `explore` | 辐射式探索 | Radiative exploration |
| `learn` | 交互式学习 | Interactive learning |
| `serve` | 启动 MCP Server | Start MCP Server |
| `setup` | 一键配置 | One-click setup |
| `generate` | 生成完整图谱 | Generate full graph |
| `plan` | 规划路径 | Plan path |
| `explain` | AI 讲解 | AI explain |
| `ask` | 对话式学习 | Conversational Q&A |
| `info` | 图谱信息 | Graph info |
| `config` | 生成 MCP 配置 | Generate MCP config |

### 接入 AI 工具 | Connect to AI Tools

```bash
nonlinear-learner serve
```

| AI 工具 | 配置文件位置 |
|---------|-------------|
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Cursor | `~/.cursor/mcp.json` |

### Python 库 | Python Library

```python
import asyncio
from nonlinear_learner import NonlinearLearner

async def main():
    engine = NonlinearLearner(llm_config={
        "endpoint": "https://api.openai.com/v1",
        "api_key": "sk-...",
        "model": "gpt-4o-mini",
    })

    # 启动学习会话 | Start learning session
    session = await engine.start_session(
        task="用 React 做一个仪表盘",
        background="会 HTML/CSS，JS 基础薄弱",
        starting_point="看到别人用 useEffect",
    )
    print(f"轨迹: {len(session.trajectory)} 步")
    for i, step in enumerate(session.trajectory):
        print(f"  {i+1}. {step.label} — {step.why_needed}")

    # 逐步讲解 | Guide step by step
    explanation = await engine.guide_current(session)
    print(explanation)

    # 推进 | Advance
    engine.advance_session(session)

    # 用户提问，调整轨迹 | Adjust trajectory
    result = await engine.adjust_session(session, "什么是闭包？")
    print(result["message"])

asyncio.run(main())
```

---

## 🔧 MCP 工具 | MCP Tools

20 个工具，其中 3 个为任务驱动学习核心工具：
20 tools, 3 core tools for guided learning:

| 工具 Tool | 说明 Description |
|-----------|-----------------|
| **`start_guided_learning`** | **启动任务驱动学习会话** |
| **`guide_next_concept`** | **讲解当前知识点并推进** |
| **`adjust_learning_path`** | **根据反馈调整轨迹** |
| `radiate_concept` | 辐射式探索 |
| `get_unexplored_concepts` | 获取未探索知识点 |
| `generate_knowledge_graph` | 生成完整图谱 |
| `plan_learning_path` | 规划路径 |
| `get_prerequisites` | 获取前置 |
| `get_suggested_next` | 推荐下一步 |
| `get_knowledge_gaps` | 知识缺口 |
| `mark_concept_mastered` | 标记掌握 |
| `add_concept` / `add_dependency` | 添加知识点/依赖 |
| `explain_concept` | AI 讲解 |
| `ask_question` | 对话学习 |
| `get_graph_info` / `get_graph_json` | 图谱信息/导出 |
| `load_graph_json` | 加载图谱 |
| `save_state` / `load_state` | 保存/加载状态 |

---

## 🏗️ 架构 | Architecture

```
src/nonlinear_learner/
├── cli.py                # CLI + guide 对话导师 + explore 辐射探索
├── core/
│   ├── models.py         # 数据模型 (含 TrajectoryStep, LearningSession)
│   ├── graph.py          # networkx DAG 操作
│   ├── pathfinder.py     # 路径规划 (3 种模式)
│   └── engine.py         # 引擎 + 会话管理 + 辐射 + SQLite
├── llm/
│   └── client.py         # LLM (unpack + guide + adjust + radiate + graph)
└── mcp_server/
    └── server.py         # FastMCP Server (20 工具)
```

**技术栈 | Tech Stack:** FastMCP + networkx + pydantic v2 + OpenAI SDK + click + SQLite

---

## 🧪 测试 | Tests

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

137 个测试覆盖会话管理、辐射学习、数据模型、DAG、路径规划、引擎、LLM 客户端。

---

## ⚙️ 配置 | Configuration

配置文件 `~/.nonlinear_learner/config.json`（由 `setup` 自动生成）：
Config at `~/.nonlinear_learner/config.json` (auto-generated by `setup`):

```json
{
  "endpoint": "https://api.openai.com/v1",
  "api_key": "sk-...",
  "model": "gpt-4o-mini"
}
```

也支持环境变量 | Also supports env vars: `OPENAI_API_KEY`, `OPENAI_ENDPOINT`, `OPENAI_MODEL`

---

## 📄 License

MIT