@rookiestar/eng-lang-tutor 1.0.1

package/references/resources.md

@@ -0,0 +1,292 @@
+# English Learning Resources
+
+> This file contains themed resources for generating authentic American English content.
+> LLM should reference these resources when generating knowledge points and quizzes.
+
+---
+
+## 1. Native American English Expressions
+
+### 1.1 Classic Learning Materials
+
+| Resource | Description | Key Features |
+|----------|-------------|--------------|
+| **Speak English Like an American** | Classic textbook with 350+ idioms | Dialogue-based learning, everyday situations |
+| **NTC's Dictionary of American Slang** | Comprehensive slang dictionary | Colloquial expressions, usage examples |
+| **American Colloquial Expressions** | Collection of spoken phrases | Almost all idioms are colloquial language |
+
+### 1.2 Common Chinglish Corrections
+
+| Chinglish (Wrong) | American (Correct) | Explanation |
+|-------------------|-------------------|-------------|
+| "It was just so-so." | "It was just ok/alright." | Americans rarely use "so-so" |
+| "Let's go out to play." | "Let's go out!" | "Play" is for children; adults "go out" |
+| "Bad for your health." | "It's not good for you." | More natural phrasing |
+| "I very like it." | "I really like it." | "Very" doesn't modify "like" |
+| "How to say?" | "How do I put this?" / "What's the word?" | Natural hesitation phrases |
+
+---
+
+## 2. TV Shows & Movies (Topic: movies)
+
+### 2.1 Recommended Shows for Learning
+
+| Show | Genre | Learning Focus | Classic Lines |
+|------|-------|----------------|---------------|
+| **Friends** | Sitcom | Daily conversation, humor, sarcasm | "How you doin'?", "Oh. My. God!" |
+| **The Office** | Workplace Comedy | Office idioms, corporate culture | "That's what she said", water-cooler chat |
+| **Gossip Girl** | Teen Drama | Youth slang, fashion, social dynamics | "No offense." / "None taken.", "Done and done." |
+| **Desperate Housewives** | Drama | Formal/informal switching, life situations | "Take a rain check", "Serves him right" |
+| **House of Cards** | Political Thriller | Business/political vocabulary, formal speech | Complex sentence structures |
+| **Modern Family** | Sitcom | Family dynamics, generational differences | "I'm not a regular mom, I'm a cool mom" |
+| **How I Met Your Mother** | Sitcom | Dating slang, friendship expressions | "Legendary", "Suit up!" |
+
+### 2.2 Expression Examples from TV Shows
+
+**From Friends:**
+- "We were on a break!" - Defending oneself
+- "Could I BE any more...?" - Emphasis (Chandler's style)
+- "Pivot!" - When moving something difficult
+
+**From The Office:**
+- "Touch base" - Briefly connect with someone
+- "Circle back" - Return to a topic later
+- "Low-hanging fruit" - Easy wins
+
+**From Gossip Girl:**
+- "Any interest in fresh air?" - Casual invitation
+- "You set me up!" - Accusing someone of a trap
+- "It was a last minute thing." - Explaining spontaneity
+
+---
+
+## 3. News & Media (Topic: news)
+
+### 3.1 News Sources for Learning
+
+| Source | Accent | Features | Topics |
+|--------|--------|----------|--------|
+| **CNN 10** | American | 10-min daily news for students | Current events, explained clearly |
+| **VOA Learning English** | American | Slow pace, simplified vocabulary | World news, American life |
+| **BBC Learning English** | British/American | Grammar focus, pronunciation | General English |
+| **Engoo** | Various | Graded by difficulty, daily updates | News, culture, lifestyle |
+| **NPR** | American | Natural pace, diverse topics | Culture, science, stories |
+
+### 3.2 News English Vocabulary
+
+**Politics & Government:**
+- bill, veto, legislation, incumbent, poll, constituency
+- "The bill passed with a narrow margin."
+- "The incumbent is seeking re-election."
+
+**Business & Economy:**
+- earnings, quarterly, forecast, market trends, inflation
+- "Stocks rallied after the announcement."
+- "The company exceeded earnings expectations."
+
+**Technology:**
+- breakthrough, innovation, cybersecurity, AI, startup
+- "The startup secured Series B funding."
+- "The breakthrough could revolutionize..."
+
+---
+
+## 4. Gaming (Topic: gaming)
+
+### 4.1 Gaming Terminology
+
+| Category | Terms & Expressions |
+|----------|-------------------|
+| **Core Terms** | NPC, spawn, respawn, loot, grind, level up, XP, HP, MP |
+| **Gameplay** | buff, nerf, patch, DLC, speedrun, playthrough |
+| **Multiplayer** | party, squad, team up, PvP, PvE, co-op, matchmaking, lobby |
+| **Competition** | GG (good game), noob, pro, clutch, carry, feed, throw, smurf |
+| **Actions** | camp, kite, tank, heal, revive, reload, flank, rush |
+
+### 4.2 Gaming Expressions in Daily Use
+
+| Expression | Meaning | Example |
+|------------|---------|---------|
+| "GG" | Good game, well done | "That presentation was GG." |
+| "Nerf" | Weaken or reduce effectiveness | "They nerfed the office coffee machine." |
+| "Grind" | Repetitive hard work | "I'm grinding through these reports." |
+| "Carry" | Do most of the work | "She carried the whole project." |
+| "Clutch" | Success under pressure | "That was a clutch presentation." |
+| "Buff up" | Improve or strengthen | "Need to buff up my resume." |
+
+### 4.3 Gaming Dialogue Examples
+
+```
+A: "Wanna squad up tonight?"
+B: "Sure, I'll be on around 8."
+A: "Cool, let's grind some ranked matches."
+B: "Hopefully we don't get matched with noobs."
+```
+
+---
+
+## 5. Sports (Topic: sports)
+
+### 5.1 Basketball Vocabulary
+
+| Category | Terms |
+|----------|-------|
+| **Scoring** | dunk, layup, three-pointer, free throw, buzzer beater |
+| **Defense** | block, steal, rebound, turnover, foul |
+| **Tactics** | pick and roll, fast break, zone defense, press |
+| **Positions** | point guard, shooting guard, forward, center |
+
+**Common Expressions:**
+- "He hit a buzzer beater to win the game!"
+- "She's on fire tonight!" (scoring consistently)
+- "They're running away with this one." (winning easily)
+- "It's a game of runs." (momentum shifts)
+
+### 5.2 Sports Idioms in Business/Daily Life
+
+| Idiom | Meaning | Example |
+|-------|---------|---------|
+| "Step up to the plate" | Take responsibility | "It's time to step up to the plate." |
+| "Ballpark figure" | Rough estimate | "Give me a ballpark figure." |
+| "Drop the ball" | Make a mistake | "Don't drop the ball on this project." |
+| "Hit it out of the park" | Do excellently | "She hit it out of the park with that pitch." |
+| "On the ball" | Alert, competent | "He's really on the ball today." |
+| "Full court press" | Intense effort | "We need a full court press on this deal." |
+
+---
+
+## 6. Workplace & Business (Topic: workplace)
+
+### 6.1 Office Idioms
+
+| Expression | Meaning | Context |
+|------------|---------|---------|
+| "Touch base" | Briefly connect | "Let's touch base next week." |
+| "Circle back" | Return to a topic | "Let's circle back on this later." |
+| "Low-hanging fruit" | Easy wins | "Let's tackle the low-hanging fruit first." |
+| "Bandwidth" | Capacity/availability | "I don't have the bandwidth for this." |
+| "Synergy" | Combined effect | "Looking for synergy between teams." |
+| "Pain point" | Problem area | "What are the customer pain points?" |
+| "Value-add" | Benefit provided | "What's the value-add here?" |
+| "Action items" | Tasks to complete | "Let's review the action items." |
+
+### 6.2 Meeting Phrases
+
+**Starting:**
+- "Let's get the ball rolling."
+- "Shall we dive in?"
+- "Thanks for hopping on this call."
+
+**Contributing:**
+- "I'd like to add something here."
+- "Building on what [name] said..."
+- "Here's my take on this."
+
+**Disagreeing Politely:**
+- "I see where you're coming from, but..."
+- "That's an interesting perspective. Have we considered...?"
+- "I'm not sure I entirely agree."
+
+**Ending:**
+- "Let's wrap this up."
+- "To summarize, we've agreed on..."
+- "I think we're good to go."
+
+### 6.3 Workplace Dialogue Examples
+
+```
+A: "Hey, do you have a minute to touch base on the project?"
+B: "Sure, what's up?"
+A: "I wanted to circle back on the timeline. We might need more bandwidth."
+B: "Got it. Let's identify the pain points and see what low-hanging fruit we can tackle first."
+```
+
+---
+
+## 7. Daily Life (Topic: daily_life)
+
+### 7.1 Shopping Expressions
+
+| Situation | Expressions |
+|-----------|-------------|
+| **Asking for help** | "Can I help you?" / "Just looking, thanks." / "Where can I find...?" |
+| **Asking about products** | "Do you have this in a different size/color?" / "Is this on sale?" |
+| **Trying on** | "Can I try this on?" / "Where's the fitting room?" |
+| **Price negotiation** | "Is this the best price?" / "Can you give me a discount?" |
+| **At checkout** | "I'll take it." / "Do you take credit cards?" / "Can I get a receipt?" |
+
+### 7.2 Restaurant Expressions
+
+| Situation | Expressions |
+|-----------|-------------|
+| **Ordering** | "I'd like the..." / "Could I get...?" / "What do you recommend?" |
+| **Special requests** | "Could I get this without...?" / "Is this vegetarian?" |
+| **During meal** | "Could I get some more water?" / "This is delicious!" |
+| **Paying** | "Could I get the check, please?" / "Separate checks, please." |
+| **To-go** | "Can I get this to go?" / "I'll have the rest to go." |
+
+### 7.3 Social Expressions
+
+**Greetings:**
+- "What's up?" / "How's it going?" / "How have you been?"
+- "Long time no see!" / "Good to see you!"
+
+**Casual Responses:**
+- "Not much, you?" / "Can't complain." / "Same old, same old."
+- "Take it easy!" / "Catch you later!" / "See ya!"
+
+**Making Plans:**
+- "We should hang out sometime." / "Let's grab coffee."
+- "Are you free this weekend?" / "What are you up to tonight?"
+
+**Polite Refusals:**
+- "I'd love to, but I can't make it." / "Maybe another time."
+- "I'll have to take a rain check."
+
+---
+
+## 8. Casual & Slang (All Topics)
+
+### 8.1 Common American Slang
+
+| Slang | Meaning | Example |
+|-------|---------|---------|
+| "Gonna" | Going to | "I'm gonna grab some food." |
+| "Gotta" | Have to | "I gotta run." |
+| "Wanna" | Want to | "Do you wanna come?" |
+| "Kinda" | Kind of | "It's kinda cold today." |
+| "Lemme" | Let me | "Lemme see that." |
+| "Dunno" | Don't know | "I dunno, maybe?" |
+| "Ya" | You | "See ya later!" |
+| "Y'all" | You all | "Y'all coming?" |
+
+### 8.2 Fillers and Hesitation
+
+| Filler | Usage |
+|--------|-------|
+| "Like" | "It was, like, really expensive." |
+| "You know" | "It's that place, you know, near the mall." |
+| "I mean" | "I mean, I could try, but..." |
+| "Sort of / Kind of" | "It's sort of complicated." |
+| "Basically" | "Basically, what happened was..." |
+| "Actually" | "Actually, I think you're right." |
+
+---
+
+## 9. Usage Notes for LLM
+
+When generating content, reference these resources based on the selected topic:
+
+1. **Movies**: Use expressions from TV shows section
+2. **News**: Reference news vocabulary and formal expressions
+3. **Gaming**: Include gaming terminology and slang
+4. **Sports**: Use sports idioms and expressions
+5. **Workplace**: Focus on office idioms and meeting phrases
+6. **Social**: Use casual greetings and social expressions
+7. **Daily Life**: Reference shopping/restaurant dialogues
+
+Always include:
+- Scene context matching the topic
+- Chinglish trap with correction
+- Natural American alternatives
+- Pronunciation tips for casual speech (gonna, gotta, etc.)

package/requirements.txt

@@ -0,0 +1,16 @@
+# Core dependencies
+websocket-client>=1.6.0  # For XunFei TTS WebSocket API
+certifi>=2024.0.0        # SSL certificate bundle for HTTPS/WebSocket connections
+aiohttp>=3.8.0           # Async HTTP client for Feishu API
+
+# Edge-TTS support (default TTS provider)
+edge-tts>=6.1.0
+
+# Development dependencies
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+
+# System dependencies (must be installed separately):
+# - ffmpeg: Required for audio composition
+#   macOS: brew install ffmpeg
+#   Ubuntu/Debian: sudo apt-get install ffmpeg

package/scripts/__init__.py

@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+"""
+eng-lang-tutor scripts package
+
+Main entry points:
+- StateManager: Core state persistence
+- Scorer: Quiz evaluation
+- GamificationManager: XP/levels/streaks/badges
+- CommandParser: User command parsing
+- AudioComposer: Audio generation
+"""
+
+from .core.state_manager import StateManager
+from .core.scorer import Scorer
+from .core.gamification import GamificationManager
+from .core.constants import LEVEL_THRESHOLDS, calculate_level, get_level_name, get_streak_multiplier
+from .core.error_notebook import ErrorNotebookManager
+
+__all__ = [
+    'StateManager',
+    'Scorer',
+    'GamificationManager',
+    'ErrorNotebookManager',
+    'LEVEL_THRESHOLDS',
+    'calculate_level',
+    'get_level_name',
+    'get_streak_multiplier',
+]

package/scripts/audio/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Audio functionality: TTS, composition, conversion, Feishu integration."""
+
+from .composer import AudioComposer, CompositionResult
+from .converter import AudioConverter, ConversionResult, convert_mp3_to_opus
+from .utils import get_ffmpeg_path, get_audio_duration
+from .feishu_voice import FeishuVoiceSender, VoiceSendResult
+from .tts import TTSManager, TTSProvider, TTSResult
+
+__all__ = [
+    'AudioComposer',
+    'CompositionResult',
+    'AudioConverter',
+    'ConversionResult',
+    'convert_mp3_to_opus',
+    'get_ffmpeg_path',
+    'get_audio_duration',
+    'FeishuVoiceSender',
+    'VoiceSendResult',
+    'TTSManager',
+    'TTSProvider',
+    'TTSResult',
+]