# 🇬🇧 pi-english-tutor

English conversation tutor plugin for [pi](https://pi.dev) — turn your coding agent into an immersive English learning environment.

> 📖 [中文文档 (Chinese README)](./README_zh.md)

## Features

| Feature | Description |
|---------|-------------|
| 🗣️ **Bilingual Mode** | AI responds in BOTH English & Chinese side-by-side |
| 🇬🇧 **English-Only Mode** | AI responds only in English for full immersion |
| 📚 **CEFR Levels** | A2 → B1 → B2 → C1 difficulty progression |
| 💡 **Error Correction** | Gentle grammar & vocabulary corrections |
| 📝 **Vocabulary Tips** | New words suggested every few exchanges |
| 🔒 **Input Guard** | Detects Chinese input — gentle reminder or strict block |
| ⌨️ **Shortcuts** | `Ctrl+Shift+E` toggle mode, `Ctrl+Shift+S` toggle strict |
| 📊 **Study Report** | Export full conversation as Markdown learning report |
| 🔌 **Pluggable** | Modular features, easy to extend |

## Quick Start

```bash
# Install from GitHub
pi install git:github.com/T-DWAG/pi-english-tutor

# Or test locally
pi -e ./extensions/english-tutor/index.ts --skill ./skills/english-tutor/SKILL.md
```

## Usage

### Commands

| Command | Action |
|---------|--------|
| `/english mode bilingual` | AI responds with 🇬🇧+🇨🇳 side by side |
| `/english mode english-only` | AI responds in 🇬🇧 only |
| `/english strict on` | Block Chinese input completely |
| `/english strict off` | Allow Chinese with gentle reminder |
| `/english difficulty A2` | Set to elementary level |
| `/english difficulty B1` | Set to intermediate |
| `/english difficulty B2` | Set to upper-intermediate |
| `/english difficulty C1` | Set to advanced |
| `/english stats` | Show current settings |
| `/english export` | Export conversation as study report |

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl+Shift+E` | Toggle bilingual ↔ english-only |
| `Ctrl+Shift+S` | Toggle strict ↔ gentle input |

### Status Bar

The footer shows current mode, difficulty, and strict status:
```
🔓 🇬🇧🇨🇳 双语 | B1
```

## Modes Explained

### Bilingual Mode (default)
The AI responds in both English and Chinese, separated clearly:

```
Your natural English response here.

---
你的中文翻译在这里。
```

Great for: building comprehension, learning vocabulary through context, and checking your understanding.

### English-Only Mode
The AI responds only in English — full immersion.

Great for: practicing reading fluency, thinking in English, and exam preparation.

## CEFR Levels

| Level | Name | What to expect |
|-------|------|----------------|
| **A2** | Elementary | Simple sentences, common words, basic tenses |
| **B1** | Intermediate | Moderate sentences, some idioms, connecting words |
| **B2** | Upper-Intermediate | Natural English, phrasal verbs, varied vocabulary |
| **C1** | Advanced | Native-like, sophisticated, nuanced |

## Architecture

```
english-tutor/
├── extensions/english-tutor/index.ts   # Main extension logic
├── skills/english-tutor/SKILL.md       # Teaching methodology
└── package.json                        # pi package manifest
```

### Extension Points (for developers)

The plugin is designed to be extended. See `extensions/english-tutor/index.ts` for the full API.

Key interfaces you can implement:
- **Translation backends** — swap LLM translation for DeepL, Google, etc.
- **Correction strategies** — custom error detection rules
- **Export formats** — Anki CSV, HTML, PDF
- **Input handlers** — spell check, grammar pre-check

## License

MIT