{"id":29477042,"url":"https://github.com/ryurex-code/08-oxford-game","last_synced_at":"2025-07-14T17:19:20.408Z","repository":{"id":300273836,"uuid":"1005171460","full_name":"Ryurex-Code/08-Oxford-Game","owner":"Ryurex-Code","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-20T18:53:41.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-20T19:55:09.474Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ryurex-Code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-19T19:39:26.000Z","updated_at":"2025-06-20T18:53:44.000Z","dependencies_parsed_at":"2025-06-20T19:55:10.879Z","dependency_job_id":"612c6e76-c793-4027-b810-30cb5afa4589","html_url":"https://github.com/Ryurex-Code/08-Oxford-Game","commit_stats":null,"previous_names":["ryurex-code/08-oxford-game"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Ryurex-Code/08-Oxford-Game","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryurex-Code%2F08-Oxford-Game","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryurex-Code%2F08-Oxford-Game/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryurex-Code%2F08-Oxford-Game/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryurex-Code%2F08-Oxford-Game/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ryurex-Code","download_url":"https://codeload.github.com/Ryurex-Code/08-Oxford-Game/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ryurex-Code%2F08-Oxford-Game/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265323823,"owners_count":23746934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-14T17:19:12.090Z","updated_at":"2025-07-14T17:19:16.706Z","avatar_url":"https://github.com/Ryurex-Code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎓 Oxford Vocabulary Trainer\n\nAn AI-powered vocabulary learning game that helps you master English words from the Oxford 3000 list using intelligent LLM translations and adaptive learning algorithms.\n\n## ✨ Features\n\n### 🎮 Game Modes\n- **Custom Mode**: Choose specific CEFR levels (A1, A2, B1, B2, C1, C2)\n- **Adventure Mode**: Random levels from A1-B2 for dynamic learning\n\n### 🤖 AI-Powered Translation\n- Uses **LLaMA 3.1 8B Instant** via Groq API for contextual Indonesian translations\n- Provides multiple meanings and contexts for each word\n- Smart fallback system for reliable operation\n- Translation caching for improved performance\n\n### 🧠 Adaptive Learning System\n- **Weighted Word Selection**: Difficult words appear more frequently\n- **Spaced Repetition**: Mastered words appear less often\n- **Performance Tracking**: Detailed statistics for each word\n- **Streak Tracking**: Monitor learning progress\n- **Smart Validation**: Precise answer checking with complete word matching\n\n### 📊 Comprehensive Statistics\n- High scores by level and game mode\n- Accuracy tracking and learning progress\n- Word mastery analysis\n- **Recently Appeared Words**: Track last 10 words that appeared in games\n- **Recently Missed Words**: Track last 10 words answered incorrectly\n- Session history with detailed breakdowns\n- **Word History Tracking**: Persistent storage of learning progress\n\n### ⚙️ Advanced Settings\n- Reset all statistics\n- Clear translation cache\n- Export statistics to JSON\n- Reset specific levels\n- **Factory Reset**: Complete data wipe back to initial state\n- Translation cache management\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Python 3.8+\n- Groq API key (free at [console.groq.com](https://console.groq.com))\n\n### Installation\n\n1. **Clone or download the project**\n   ```bash\n   cd oxford_vocab_trainer\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Configure API key**\n   ```bash\n   # Copy the example environment file\n   copy .env.example .env\n   \n   # Edit .env and add your Groq API key\n   GROQ_API_KEY=your_groq_api_key_here\n   ```\n\n4. **Run the game**\n   ```bash\n   python main.py\n   ```\n\n### Getting Groq API Key\n\n1. Visit [console.groq.com](https://console.groq.com)\n2. Sign up for a free account\n3. Navigate to API Keys section\n4. Create a new API key\n5. Copy the key to your `.env` file\n\n## 🎯 How to Play\n\n### Custom Mode\n1. Select **Custom Mode** from main menu\n2. Choose your desired CEFR level (A1-C2)\n3. Translate English words to Indonesian\n4. Build your score with correct answers\n5. Game ends on first wrong answer\n\n### Adventure Mode\n1. Select **Adventure Mode** for random levels\n2. Face words from A1-B2 levels randomly\n3. Test your knowledge across different difficulties\n4. Challenge yourself with unpredictable vocabulary\n\n### Game Controls\n- **Type your answer**: Indonesian translation of the word\n- **'hint'**: Get a clue for the current word\n- **'skip'**: Skip the current word (counts as wrong)\n- **'quit'**: End the current game session\n\n## 🏗️ Project Structure\n\n```\noxford_vocab_trainer/\n│\n├── data/\n│   ├── oxford_3000.csv         # Oxford 3000 word list\n│   └── oxford_5000.csv         # Oxford 5000 word list (optional)\n│\n├── src/\n│   ├── game.py                 # Game logic and scoring\n│   ├── translator.py           # LLM translation handler\n│   ├── word_picker.py          # Adaptive word selection\n│   └── utils.py                # Utility functions\n│\n├── scores/\n│   ├── top_score.json          # High scores storage\n│   ├── word_weights.json       # Word difficulty weights\n│   ├── word_history.json       # Recently appeared and missed words\n│   └── current_session.json    # Current session data\n│\n├── main.py                     # Entry point\n├── requirements.txt            # Dependencies\n├── .env.example               # Environment template\n└── README.md                  # This file\n```\n\n## 🧠 Learning Algorithm\n\nThe app uses an intelligent adaptive learning system:\n\n### Word Weighting System\n- **High accuracy words (80%+)**: Lower weight → appear less often\n- **Low accuracy words (\u003c40%)**: Higher weight → appear more often\n- **Consecutive correct answers**: Significantly reduce weight\n- **Consecutive wrong answers**: Significantly increase weight\n\n### Performance Tracking\n- Accuracy percentage per word\n- Consecutive correct/wrong streaks\n- Last seen timestamp\n- Total attempts and success rate\n\n### Spaced Repetition\n- Words you struggle with get priority\n- Mastered words fade into background\n- New words get slight boost in selection\n\n## 📊 Statistics \u0026 Features\n\n### Score Tracking\n- Overall high score\n- High scores by CEFR level\n- High scores by game mode\n- Session history (last 20 sessions)\n\n### Learning Analytics\n- Words needing practice\n- Recently mastered words\n- Level-wise mastery percentage\n- Accuracy trends\n\n### Export \u0026 Reset\n- Export all statistics to JSON\n- Reset individual levels\n- Clear translation cache\n- Full statistics reset\n- **Factory Reset**: Complete data wipe to restore initial state\n- **Word History Management**: Track and review learning progress\n\n## � Enhanced Statistics \u0026 Features\n\n### Score Tracking\n- Overall high score\n- High scores by CEFR level\n- High scores by game mode\n- Session history (last 20 sessions)\n- **New Record Notifications**: Celebrate achievements\n\n### Learning Analytics\n- Words needing practice\n- Recently mastered words\n- Level-wise mastery percentage\n- Accuracy trends\n- **Recently Appeared Words (Last 10)**: See what words you've encountered\n- **Recently Missed Words (Last 10)**: Focus on words that need practice\n\n### Smart Answer Validation\n- **Precise word matching**: No more partial answers being accepted\n- **Complete word validation**: \"kap\" won't be accepted for \"kapal\"\n- **Multi-word support**: Handle compound translations correctly\n- **Case-insensitive matching**: Focus on meaning, not capitalization\n\n### Session Summary Enhancements\n- **Complete answer display**: All correct meanings shown (no truncation)\n- **Detailed wrong answer breakdown**: See exactly what you got wrong\n- **Performance metrics**: Accuracy, streak, and level breakdown\n\n### AI Translation\n- **Model**: LLaMA 3.1 8B Instant via Groq API\n- **Features**: \n  - Contextual translation with multiple meanings\n  - **Advanced caching system** for performance optimization\n  - **Persistent cache storage** for offline capability\n  - Fallback dictionary for reliability\n  - Error handling and retries\n  - **Smart retry logic** with exponential backoff\n\n### Answer Validation Engine\n- **Intelligent word matching**: Complete word validation only\n- **Multi-word phrase support**: Handle complex translations\n- **Boundary detection**: Prevent substring false positives\n- **Flexible matching**: Support various answer formats while maintaining accuracy\n\n### Data Processing \u0026 Storage\n- **Source**: Oxford 3000/5000 word lists\n- **Format**: CSV with word, class (part of speech), level\n- **Validation**: Automatic data cleaning and validation\n- **Persistent History**: Word appearance and error tracking\n- **Efficient Storage**: JSON-based data persistence\n\n### Performance Optimizations\n- **Advanced translation caching** to reduce API calls\n- **Persistent cache storage** for faster subsequent sessions\n- Weighted random selection for balanced gameplay\n- Efficient data structures for statistics\n- **Background auto-saving** of progress\n- **Factory reset capability** for clean starts\n\n## 🎮 Game Modes Explained\n\n### Custom Mode\nPerfect for focused learning:\n- Choose specific CEFR level\n- Systematic vocabulary building\n- Track progress per level\n- Ideal for structured learning\n\n### Adventure Mode\nFor dynamic challenge:\n- Random levels A1-B2\n- Unpredictable difficulty\n- Broader vocabulary exposure\n- Fun and engaging experience\n\n## 📈 Learning Tips\n\n1. **Start with A1**: Build foundation before advancing\n2. **Use hints wisely**: Learn from partial clues\n3. **Review statistics**: Identify weak areas\n4. **Regular practice**: Consistency improves retention\n5. **Challenge yourself**: Try Adventure mode when confident\n\n## 🔧 Configuration\n\n### Environment Variables\n```bash\n# Required\nGROQ_API_KEY=your_groq_api_key_here\n\n# Optional\nDEFAULT_DATASET=oxford_3000\nMAX_RETRIES=3\nTRANSLATION_TIMEOUT=10\n```\n\n### Customization\n- Modify word weights in `word_picker.py`\n- Adjust translation prompts in `translator.py`\n- Customize UI colors in `utils.py`\n- Add new game modes in `game.py`\n\n## 🤝 Contributing\n\nContributions are welcome! Areas for improvement:\n- Additional language support\n- GUI interface (Gradio/Streamlit)\n- Mobile app version\n- More game modes\n- Enhanced AI prompts\n\n## 📄 License\n\nThis project is open source. Feel free to use, modify, and distribute.\n\n## 🙏 Acknowledgments\n\n- **Oxford University Press** for the Oxford 3000/5000 word lists\n- **Groq** for providing fast LLM inference\n- **LLaMA** team for the language model\n- **Python community** for excellent libraries\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**ImportError: No module named 'package'**\n```bash\npip install -r requirements.txt\n```\n\n**Translation fails**\n- Check Groq API key in `.env`\n- Verify internet connection\n- Check API quota/limits\n\n**No words available**\n- Verify CSV files in `data/` directory\n- Check file format and headers\n- Ensure proper CEFR level filtering\n\n**Performance issues**\n- Clear translation cache in settings\n- Reset word statistics if needed\n- Check available disk space\n\n### Testing Installation\n```bash\npython main.py --test\n```\n\nThis runs a quick test to verify:\n- Environment configuration\n- Data file loading\n- API connectivity\n- Translation functionality\n\n## 📞 Support\n\nFor issues or questions:\n1. Check this README\n2. Review error messages carefully\n3. Test with `python main.py --test`\n4. Verify API key and internet connection\n\n---\n\n**Happy Learning! 🎓📚**\n\nMaster English vocabulary with the power of AI and adaptive learning!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryurex-code%2F08-oxford-game","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryurex-code%2F08-oxford-game","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryurex-code%2F08-oxford-game/lists"}