A Discord bot powered by GitHub Models (GPT-4o) that helps users learn a new language through guided lessons, free conversation, writing drills, and audio listening practice. User profiles and progress are persisted with SQLite.
| Command | Type | Description |
|---|---|---|
/chat <message> |
Slash | Free conversation in your target language. The bot stays in character and adapts to your level. |
/lesson [message] |
Slash | Guided curriculum lesson. Leave blank to start — the tutor kicks off the scenario. |
/lesson_done |
Slash | Mark the current lesson complete and advance to the next one. |
/lesson_info |
Slash | View the overview of your current lesson (topic, vocab, grammar, goal). |
/lesson_progress |
Slash | See your full curriculum progress with a visual progress bar. |
Every /chat and /lesson reply includes clickable hint buttons (💡 1 – 💡 6) below the message. Hints are ordered from least to most revealing:
- Key vocabulary word + meaning
- Second vocab item or expression
- Grammar/conjugation breakdown with rules
- Kanji/character meanings + mnemonics (non-Latin scripts)
- Cultural or usage note
- Full English translation
Click any button to reveal that hint — go in any order you like.
Japanese learners follow a 23-lesson curriculum mapped to the Genki textbook series:
- Genki I (Lessons 1–12): Greetings → Te-form → Short forms → Feeling Ill
- Genki II (Lessons 13–23): Potential verbs → Honorific speech → Passive/Causative → Capstone
The AI tutor sticks to Genki grammar patterns and vocabulary appropriate to each chapter.
All other languages use a 12-lesson general curriculum.
| Command | Type | Description |
|---|---|---|
!practice <script> [set] |
Prefix | Interactive quiz on writing system characters. |
!scripts |
Prefix | List available scripts for your language. |
!chart |
Prefix | View the full character chart for a script. |
!practice_reset |
Prefix | Reset your practice session. |
Supported scripts: Hiragana (12 sets), Katakana (12), Kanji/JLPT N5 (6), Hangul (5), Arabic (4), Cyrillic (4), Devanagari (4), Mandarin Pinyin (3).
| Command | Type | Description |
|---|---|---|
!listen <text> |
Prefix | Hear any text spoken aloud by a neural voice. |
TTS audio is also auto-attached to every /chat and /lesson reply. Speech speed adjusts by proficiency level (slower for beginners).
15 languages supported via Microsoft Edge neural voices.
| Command | Type | Description |
|---|---|---|
!feedback <text> |
Prefix | Submit writing for structured grammar/vocabulary feedback. |
!profile |
Prefix | View your language, level, and progress stats. |
!setlanguage <lang> |
Prefix | Switch target language (resets chat history). |
!setlevel <level> |
Prefix | Set proficiency: beginner / intermediate / advanced. |
!chat_reset |
Prefix | Clear conversation history and start fresh. |
!lesson_reset |
Prefix | Clear lesson chat and restart the current lesson. |
!reminders on/off |
Prefix | Toggle daily practice reminders. |
The bot auto-promotes your level after 10 feedback sessions with mostly clean attempts.
- Daily reminder (9:00 AM UTC): Nudges opted-in users with their current lesson info.
- Weekly report (Sundays 10:00 AM UTC): Progress summary with lessons completed that week.
Commands can be restricted to specific Discord channels via .env. This keeps conversations, feedback, lessons, and practice in dedicated channels.
Spanish · French · German · Italian · Portuguese · Japanese · Korean · Mandarin · Arabic · Russian · Hindi · Dutch · Swedish · Polish · Turkish
- Python 3.11+
- A Discord application
- A GitHub account (for GitHub Models API)
pip install -r requirements.txtcp .env.example .env
# Edit .env and fill in your tokens and channel IDs| Variable | Description |
|---|---|
DISCORD_TOKEN |
Discord Developer Portal → your app → Bot → Token |
GITHUB_TOKEN |
GitHub Settings → Tokens — classic PAT, no special scopes |
GITHUB_MODEL |
Model name (default: gpt-4o) |
CHANNEL_CHAT |
Channel ID for /chat commands |
CHANNEL_FEEDBACK |
Channel ID for !feedback |
CHANNEL_LESSONS |
Channel ID for /lesson commands |
CHANNEL_PRACTICE |
Channel ID for !practice commands |
CHANNEL_STARTUP |
Channel ID for the bot's startup message |
In the Discord Developer Portal:
- Go to OAuth2 → URL Generator
- Select scopes:
bot,applications.commands - Select permissions: View Channels, Send Messages, Embed Links, Attach Files
- Open the generated URL and invite to your server
python bot.py├── bot.py # Entry point — sets up the bot, loads cogs, startup message
├── ai_client.py # Async GitHub Models HTTP client
├── session.py # SQLite-backed user profiles, curriculum progress, reminders
├── prompts.py # All system prompts (chat, feedback, lesson, practice)
├── curriculum.py # Genki I & II (Japanese) + general 12-lesson curriculum
├── scripts.py # Writing system data (Hiragana, Katakana, Kanji, Hangul, etc.)
├── hints.py # Tiered hint system with Discord buttons
├── tts.py # Edge-TTS neural voice wrapper (15 languages)
├── commands/
│ ├── __init__.py
│ ├── channels.py # Channel restriction decorators
│ ├── chat.py # /chat, !chat_reset
│ ├── feedback.py # !feedback
│ ├── lesson.py # /lesson, /lesson_done, /lesson_info, /lesson_progress, !lesson_reset, !reminders
│ ├── listen.py # !listen (TTS)
│ ├── practice.py # !practice, !scripts, !chart, !practice_reset
│ ├── profile.py # !profile, !setlanguage, !setlevel
│ └── reminders.py # Background tasks: daily reminders, weekly reports
├── requirements.txt
├── .env.example
└── .gitignore
User profiles, proficiency levels, feedback stats, lesson plans, and completion progress are stored locally in a SQLite database (language_bot.db). Chat history is kept in memory and resets when the bot restarts.
All AI prompts live in prompts.py. Each prompt uses {language} and {level} placeholders. Edit them freely to change the bot's persona, the feedback format, or the breakdown structure.