{"id":43738897,"url":"https://github.com/bigspawn/anki-bot","last_synced_at":"2026-02-05T11:11:02.174Z","repository":{"id":304337119,"uuid":"1018487087","full_name":"bigspawn/anki-bot","owner":"bigspawn","description":"German Learning Telegram Bot Like Anki ","archived":false,"fork":false,"pushed_at":"2025-07-20T11:58:07.000Z","size":437,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-20T12:24:30.991Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/bigspawn.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-07-12T11:15:17.000Z","updated_at":"2025-07-20T11:57:25.000Z","dependencies_parsed_at":"2025-07-12T13:34:48.887Z","dependency_job_id":null,"html_url":"https://github.com/bigspawn/anki-bot","commit_stats":null,"previous_names":["bigspawn/anki-bot"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/bigspawn/anki-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigspawn%2Fanki-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigspawn%2Fanki-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigspawn%2Fanki-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigspawn%2Fanki-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigspawn","download_url":"https://codeload.github.com/bigspawn/anki-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigspawn%2Fanki-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29120485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T10:47:47.471Z","status":"ssl_error","status_checked_at":"2026-02-05T10:45:08.119Z","response_time":65,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-02-05T11:11:01.399Z","updated_at":"2026-02-05T11:11:02.163Z","avatar_url":"https://github.com/bigspawn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# German Learning Telegram Bot\n\nA Telegram bot for learning German language through intelligent word addition and spaced repetition system.\n\n## 🎯 Features\n\n- **Smart Word Addition**: Extract German words from text with automatic analysis\n- **Spaced Repetition**: SuperMemo 2 algorithm for optimal learning\n- **OpenAI Integration**: Automatic word processing with translations and examples (GPT-4/O1 models)\n- **Progress Tracking**: Detailed learning statistics and progress monitoring\n- **User-Friendly Interface**: Intuitive Telegram bot commands\n- **Multi-User Support**: Isolated user sessions with concurrent study support\n- **Rate Limiting**: Built-in protection against API abuse and system overload\n- **User Authorization**: Configurable access control with allowed users list\n- **Docker Support**: Full containerization for easy deployment\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- [UV package manager](https://docs.astral.sh/uv/)\n- Telegram Bot Token (from [@BotFather](https://t.me/botfather))\n- OpenAI API Key\n\n### Installation\n\n```bash\n# Install UV\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and setup\ngit clone \u003crepository-url\u003e\ncd anki-bot\nuv sync --dev\n\n# Setup environment\ncp .env.example .env\n# Edit .env with your tokens\n\n# Initialize database\nuv run python -c \"from src.database import init_db; init_db()\"\n\n# Start bot (or use Makefile)\nuv run python main.py\n# OR\nmake run\n```\n\n## 🤖 Bot Commands\n\n- `/start` - Welcome and instructions\n- `/add \u003ctext\u003e` - Add German words from text\n- `/study` - Start spaced repetition session\n- `/study_new` - Study only new words\n- `/study_difficult` - Review difficult words\n- `/stats` - Show learning statistics\n- `/settings` - Configure session settings\n- `/help` - Command help\n\n## 📖 Usage Examples\n\n### Adding Words\n\n```\n/add Ich gehe heute in die Schule und treffe meine Freunde.\n```\n\nThe bot will:\n1. Extract German words from the text\n2. Analyze each word with OpenAI (lemma, part of speech, article)\n3. Generate translations and example sentences\n4. Add words to your personal vocabulary\n\n### Study Session\n\n```\n/study\n```\n\nInteractive flashcard session with:\n- Word presentation (German side)\n- Show answer button\n- Rating system: ❌ Again | ➖ Hard | ➕ Good | ✅ Easy\n- Automatic interval calculation using SuperMemo 2\n\n### Automatic Text Processing\n\nSimply send any German text to the bot:\n\n```\nDas Wetter ist heute sehr schön und warm.\n```\n\nThe bot automatically extracts and processes words for learning.\n\n## 🏗️ Architecture\n\n### Core Components\n\n- **`database.py`** - SQLite database management\n- **`word_processor.py`** - OpenAI API integration for word analysis\n- **`text_parser.py`** - German text parsing and word extraction\n- **`spaced_repetition.py`** - SuperMemo 2 algorithm implementation\n- **`bot_handler.py`** - Telegram bot interface\n- **`utils.py`** - Utility functions and helpers\n\n### Database Schema\n\n```sql\n-- Users management\nCREATE TABLE users (\n    id INTEGER PRIMARY KEY,\n    telegram_id INTEGER UNIQUE,\n    username TEXT,\n    created_at TIMESTAMP\n);\n\n-- Word storage\nCREATE TABLE words (\n    id INTEGER PRIMARY KEY,\n    user_id INTEGER,\n    word TEXT,\n    lemma TEXT,\n    part_of_speech TEXT,\n    article TEXT,\n    translation TEXT,\n    example TEXT,\n    FOREIGN KEY (user_id) REFERENCES users(id)\n);\n\n-- Learning progress tracking\nCREATE TABLE learning_progress (\n    id INTEGER PRIMARY KEY,\n    user_id INTEGER,\n    word_id INTEGER,\n    easiness_factor REAL DEFAULT 2.5,\n    interval_days INTEGER DEFAULT 1,\n    repetitions INTEGER DEFAULT 0,\n    next_review_date DATE,\n    FOREIGN KEY (user_id) REFERENCES users(id),\n    FOREIGN KEY (word_id) REFERENCES words(id)\n);\n```\n\n## 🧪 Development\n\n### Makefile Commands\n\n```bash\n# Show all available commands\nmake help\n\n# Install dependencies\nmake install\n\n# Run the bot\nmake run\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Lint code\nmake lint\n\n# Format code\nmake format\n\n# Complete development workflow (format + lint + test)\nmake dev\n```\n\n### Running Tests\n\n```bash\n# All tests\nmake test\n# OR manually:\nuv run pytest tests/ -v\n\n# Specific test suite\nuv run pytest tests/test_database.py -v\nuv run pytest tests/test_spaced_repetition.py -v\nuv run pytest tests/test_word_processor.py -v\n\n# Integration tests\nuv run pytest tests/test_integration.py -v\n\n# With coverage\nmake test-cov\n```\n\n### Code Quality\n\n```bash\n# Formatting and linting with Ruff\nmake format\nmake lint\n\n# Security checks\nmake security\n\n# All development checks\nmake dev\n\n# Legacy tools (if needed)\nuv run ruff format src/ tests/\nuv run ruff check src/ tests/\nuv run mypy src/ --ignore-missing-imports\nuv run bandit -r src/\nuv run safety check\n\n# Pre-commit hooks\nuv run pre-commit install\nuv run pre-commit run --all-files\n```\n\n### Development with Mock Data\n\nFor development without OpenAI API calls:\n\n```python\nfrom src.word_processor import get_word_processor\n\n# Use mock processor (no API calls)\nprocessor = get_word_processor(use_mock=True)\n```\n\n## 🚀 CI/CD Pipeline\n\nThe project includes comprehensive GitHub Actions workflows:\n\n### Automated Testing\n- **Tests**: Run on every push and PR\n- **Coverage**: Codecov integration with detailed reports\n- **Security Scans**: Bandit, Safety, and Trivy vulnerability scanning\n- **Multi-platform**: Linux AMD64 and ARM64 support\n\n### Docker Images\n- **Automatic Builds**: Multi-architecture Docker images on every release\n- **Registry**: Published to GitHub Container Registry (ghcr.io)\n- **Security**: Container vulnerability scanning with Trivy\n\n### Security \u0026 Quality\n- **Manual Security Scans**: On-demand vulnerability scanning with Trivy\n- **Code Quality**: Automated linting and type checking\n- **Manual Triggers**: All security scans run only when needed\n\n### Release Automation\n```bash\n# Create a new release\ngit tag v1.0.0\ngit push origin v1.0.0\n\n# This automatically:\n# 1. Runs all tests and security scans\n# 2. Builds multi-platform Docker images\n# 3. Creates GitHub release with changelog\n# 4. Publishes to GitHub Container Registry\n```\n\n## 🐳 Docker Deployment\n\n### Docker Compose (Recommended)\n\n```bash\n# Setup environment\ncp .env.example .env\n# Edit .env with your tokens\n\n# Deploy\ndocker-compose up --build -d\n\n# View logs\ndocker-compose logs -f german-bot\n\n# Stop\ndocker-compose down\n```\n\n### Manual Docker\n\n```bash\n# Build\ndocker build -t german-bot -f docker/Dockerfile .\n\n# Run\ndocker run -d --name german-bot \\\n  --env-file .env \\\n  -v $(pwd)/data:/app/data \\\n  -v $(pwd)/logs:/app/logs \\\n  german-bot\n```\n\n## ⚙️ Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `TELEGRAM_BOT_TOKEN` | Telegram bot token | - | ✅ |\n| `OPENAI_API_KEY` | OpenAI API key | - | ✅ |\n| `DATABASE_URL` | Database path | `sqlite:///data/bot.db` | ❌ |\n| `LOG_LEVEL` | Logging level | `INFO` | ❌ |\n| `MAX_WORDS_PER_REQUEST` | Max words per /add | `50` | ❌ |\n| `MAX_WORDS_PER_DAY` | Daily word limit | `100` | ❌ |\n| `MAX_OPENAI_REQUESTS_PER_DAY` | Daily OpenAI API limit | `200` | ❌ |\n| `ALLOWED_USERS` | Comma-separated user IDs | `\"\"` (all blocked) | ❌ |\n| `POLLING_INTERVAL` | Bot polling interval | `1.0` | ❌ |\n\n### OpenAI Settings\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `OPENAI_MODEL` | Model to use | `gpt-4` |\n| `OPENAI_MAX_TOKENS` | Max completion tokens | `1000` |\n| `OPENAI_TEMPERATURE` | Model temperature | `1.0` |\n\n**Note**: GPT-4 and O1 models require `OPENAI_TEMPERATURE=1.0`. Use `max_completion_tokens` instead of deprecated `max_tokens`.\n\n### User Authorization\n\nControl access to your bot with the `ALLOWED_USERS` environment variable:\n\n```bash\n# Allow specific users only (comma-separated Telegram user IDs)\nALLOWED_USERS=\"321,123,456\"\n\n# Allow single user\nALLOWED_USERS=\"321\"\n\n# Block all users (default behavior)\nALLOWED_USERS=\"\"\n```\n\n**Security Features:**\n- Empty or unset `ALLOWED_USERS` blocks all access\n- Unauthorized users receive polite denial message\n- Access attempts are logged for monitoring\n- User IDs can be found in Telegram logs when users interact with bot\n\n## 📊 Spaced Repetition System\n\nUses SuperMemo 2 algorithm with four difficulty ratings:\n\n- **❌ Again** (\u003c 1 min): Reset interval, review in current session\n- **➖ Hard** (\u003c 6 min): Interval × 1.2, decrease easiness factor\n- **➕ Good** (\u003c 10 min): Interval × easiness factor\n- **✅ Easy** (4 days): Interval × easiness factor × 1.3\n\n### Learning Algorithm\n\n1. **New words**: Start with 1-day interval\n2. **Successful reviews**: Increase interval based on easiness factor\n3. **Failed reviews**: Reset interval and decrease easiness\n4. **Graduation**: Words become \"learned\" after successful repetitions\n\n## 🔒 Security \u0026 Limits\n\n- Maximum 50 words per `/add` command\n- Maximum 100 words per day per user\n- Maximum 200 OpenAI API requests per day\n- 60-second timeout for API requests\n- Encrypted API keys storage\n\n## 📈 Monitoring\n\n### Logging\n\n```bash\n# View logs\ntail -f logs/bot.log\n\n# Search for errors\ngrep ERROR logs/bot.log\n\n# Monitor API usage\ngrep \"OpenAI\" logs/bot.log\n```\n\n### Health Checks\n\n```bash\n# Test database\nuv run python -c \"from src.database import init_db; init_db(); print('DB OK')\"\n\n# Test OpenAI connection\nuv run python -c \"\nimport asyncio\nfrom src.word_processor import WordProcessor\nasync def test():\n    processor = WordProcessor()\n    result = await processor.test_connection()\n    print(f'OpenAI: {result}')\nasyncio.run(test())\n\"\n```\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n**Bot not responding**\n- Verify `TELEGRAM_BOT_TOKEN` is correct\n- Check if bot is already running elsewhere\n- Review logs for errors\n\n**OpenAI errors**\n- Confirm `OPENAI_API_KEY` is valid\n- Check OpenAI account has credits\n- Verify model availability\n\n**Database errors**\n- Ensure `data/` directory is writable\n- Re-initialize database if corrupted\n- Check file permissions\n\n### Getting Help\n\n1. Check logs for specific error messages\n2. Review [setup documentation](docs/SETUP.md)\n3. Test individual components\n4. Create GitHub issue with logs and configuration\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests (`uv run pytest tests/ -v`)\n4. Commit changes (`git commit -m 'Add amazing feature'`)\n5. Push to branch (`git push origin feature/amazing-feature`)\n6. Open Pull Request\n\n## 🎯 Roadmap\n\n### Phase 2 Features\n- Audio pronunciation support\n- Grammar exercises\n- Anki deck export\n- Statistics by time zones\n\n### Phase 3 Features\n- Group challenges\n- Integration with other services\n- Mobile application\n- Multi-language support\n\n---\n\n**Made with ❤️ for German language learners**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigspawn%2Fanki-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigspawn%2Fanki-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigspawn%2Fanki-bot/lists"}