Telegram AI English Tutor Bot Development

Telegram AI English Tutor Bot Development Project Overview We are looking for an experienced Python developer to build an AI-powered Telegram bot that helps users learn and practice English. The bot should communicate with users through text and voice messages, identify their English level, correct mistakes, explain grammar, suggest better phrases, and generate personalized exercises. The project should be developed as a production-ready MVP with a clean and extensible architecture. Main User Flow The user starts the bot using the /start command. The bot asks the user to select: Native language Current English level Learning goal Preferred communication format The user completes a short English level assessment. The bot creates a basic learning profile. The user can communicate with the AI tutor using text or voice messages. The bot analyzes the user's messages, corrects mistakes, and continues the conversation. The bot stores the user's progress and adapts future exercises to their level. Target English Levels The bot should support the following CEFR levels: Beginner — A1 Elementary — A2 Intermediate — B1 Upper Intermediate — B2 Advanced — C1 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. • • • • • 1 Core Features 1. Telegram Bot The bot must support: /start /help /profile /practice /lesson /vocabulary /progress /settings /subscription The interface should use Telegram inline buttons where appropriate. 2. AI Conversation Mode The user should be able to have a natural conversation with the AI tutor. The bot should: Respond according to the user's English level Keep answers concise and easy to understand Correct grammar and vocabulary mistakes Suggest more natural phrases Explain corrections in the user's native language Ask follow-up questions Remember the context of the current conversation Example: User: Yesterday I go to cinema with my friend. Bot: Yesterday I went to the cinema with my friend. Explanation: We use “went” because the action happened in the past. “Went” is the past form of “go”. • • • • • • • • • • • • • • • • 2 Then the bot should continue the conversation: What movie did you watch? 3. Conversation Modes The user should be able to select a practice mode: General conversation Travel English Business English Job interview preparation English for IT professionals Grammar practice Vocabulary practice Role-playing scenarios Example role-playing scenarios: Ordering food in a restaurant Checking into a hotel Speaking with a recruiter Participating in a work meeting Talking to a customer Going through airport security 4. Level Assessment The bot should include a short initial assessment. The assessment may contain: Multiple-choice questions Grammar questions Vocabulary questions Short written answers A short conversation with the AI Based on the answers, the bot should estimate the user's English level. The assessment algorithm does not need to be academically certified. It should provide a reasonable approximate result for personalization. 5. Personalized Lessons The bot should generate short lessons based on: User level • • • • • • • • • • • • • • • • • • • • 3 Learning goals Previous mistakes Recently learned vocabulary Selected topic Each lesson may include: Short explanation Examples Exercise User answer AI feedback Additional practice question 6. Mistake Tracking The bot should store common user mistakes. Mistake categories: Grammar Vocabulary Word order Articles Prepositions Verb tense Spelling Style and natural phrasing The AI should use previous mistakes when generating future exercises. 7. Vocabulary Trainer Users should be able to save words and phrases to their personal vocabulary list. For every saved word, store: Word or phrase Translation Example sentence Date added Number of correct answers Number of incorrect answers Next review date The bot should periodically offer vocabulary revision exercises. A simplified spaced-repetition algorithm is acceptable for the MVP. • • • • 1. 2. 3. 4. 5. 6. • • • • • • • • • • • • • • • 4 8. Voice Messages The bot should accept Telegram voice messages. Required processing flow: Receive Telegram voice message Download the audio file Convert audio when necessary Transcribe speech using a speech-to-text API Send the transcription to the LLM Generate corrections and a response Return a text response to the user Optional feature: Generate an audio response using a text-to-speech API 9. User Progress The bot should show basic learning statistics: Current English level Number of completed lessons Number of practice sessions Number of learned words Most common mistakes Total study time Current learning streak The /progress command should display a short progress summary. 10. LLM Integration The bot should support at least one LLM provider, such as: OpenAI Anthropic Google Gemini The LLM provider must be configurable through environment variables. The implementation should separate the business logic from the specific LLM provider so another provider can be added later. The system prompt should include: User level 1. 2. 3. 4. 5. 6. 7. • • • • • • • • • • • • 5 Native language Learning goal Current practice mode Recent mistakes Relevant conversation context The bot must not send the entire conversation history to the LLM on every request. A conversation summarization or limited-context strategy should be implemented. 11. Free and Premium Plans The MVP should support two access levels. Free plan: Limited number of AI messages per day Limited voice-message usage Basic conversation mode Basic progress statistics Premium plan: Higher or unlimited message limits Voice-message support Personalized lessons Full progress history Vocabulary trainer All conversation modes Payment integration may be implemented using Telegram Stars or another agreed payment provider. For the first version, the developer may implement subscription status without real payments, provided the architecture allows payment integration later. 12. Admin Features A simple admin interface or admin commands should provide: Total number of users Number of active users Number of new users Number of LLM requests Approximate token usage Approximate API costs User blocking Granting or removing premium access Sending a broadcast message • • • • • • • • • • • • • • • • • • • • • • • • 6 A web-based admin panel is optional for the MVP. Telegram admin commands are acceptable. Technical Requirements Preferred technology stack: Python 3.12+ aiogram 3.x FastAPI PostgreSQL SQLAlchemy 2.x Alembic Redis OpenAI, Anthropic, or Gemini API Docker Docker Compose Suggested architecture: Telegram bot application API or application service LLM integration layer Speech-to-text integration Database layer Background worker Redis for caching and rate limiting The project should use asynchronous Python where appropriate. Suggested Database Entities The database should include entities similar to: User ID Telegram user ID Username Native language English level Learning goal Subscription type Subscription expiration date Created date Last activity date • • • • • • • • • • • • • • • • • • • • • • • • • • • 7 Conversation ID User ID Conversation mode Short conversation summary Created date Updated date Message ID Conversation ID Role Message text Token usage Created date UserMistake ID User ID Original text Corrected text Explanation Mistake category Created date VocabularyItem ID User ID Word or phrase Translation Example Correct-answer count Incorrect-answer count Next review date Lesson ID User ID Topic Level Lesson content Completion status Created date Completed date • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • 8 UsageRecord ID User ID Request type Input tokens Output tokens Estimated cost Created date Rate Limiting and Cost Control The system must include: Daily message limits Voice-message duration limits Maximum input-message length Maximum LLM response length Per-user rate limiting Protection from repeated requests Token-usage logging Configurable LLM model Configurable daily limits The bot should display a friendly message when a user reaches a limit. Error Handling The application should correctly handle: Telegram API errors LLM API timeouts LLM rate limits Invalid audio files Speech-to-text failures Database connection errors Duplicate Telegram updates Unexpected model responses Errors should be logged without exposing sensitive information to users. Security Requirements API keys must be stored in environment variables. Secrets must not be committed to the repository. User input must be validated. Admin functionality must be restricted by Telegram user ID. • • • • • • • • • • • • • • • • • • • • • • • • • • • • 9 Logs must not contain API keys or complete sensitive user data. Webhook endpoints must be protected using a secret token. Database queries must use the ORM or safe parameterized queries. Deployment The application should be delivered with: Dockerfile Docker Compose configuration .env.example Database migrations Production startup instructions Webhook configuration instructions Basic backup instructions The bot should be deployable to a standard VPS. Possible deployment targets: DigitalOcean Hetzner AWS Google Cloud Railway Render Testing The project should include tests for the main business logic. Minimum expected coverage: User registration English-level selection Daily request limits LLM service integration using mocks Saving mistakes Vocabulary review Subscription-access checks Telegram command handlers External APIs must be mocked in automated tests. • • • • • • • • • • • • • • • • • • • • • • • • 10 Logging and Monitoring The application should provide structured logs for: Incoming requests Telegram update processing LLM requests LLM response time Token usage Errors Background tasks Optional integrations: Sentry Prometheus Grafana Deliverables The developer must provide: Complete source code Git repository Docker configuration Database migrations .env.example Setup and deployment documentation Basic architecture documentation Automated tests API and LLM configuration instructions A deployed working version of the bot Development Milestones Milestone 1 — Project Setup and Basic Telegram Bot Project structure Docker configuration PostgreSQL integration User registration Basic commands Settings and profile Milestone 2 — LLM Tutor LLM integration • • • • • • • • • • 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. • • • • • • • 11 Conversation mode Prompt management Grammar correction Conversation context Request limits Milestone 3 — Learning Features Level assessment Lessons Mistake tracking Vocabulary trainer Progress statistics Milestone 4 — Voice and Subscription Features Voice-message transcription Premium-access logic Usage and cost tracking Admin commands Milestone 5 — Testing and Deployment Automated tests Error handling Production deployment Documentation Final bug fixing Acceptance Criteria The project will be considered complete when: A new user can register and configure a learning profile. The bot can hold an English conversation using an LLM. The bot corrects user mistakes and explains corrections. Conversation context is preserved. User mistakes and vocabulary are stored. The bot can generate personalized exercises. Voice messages can be transcribed and processed. Daily limits work correctly. Admins can view basic usage statistics. The project runs through Docker Compose. Database migrations work on a clean database. The main functionality is covered by automated tests. Deployment and configuration instructions are provided. • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • • 12 Developer Requirements Please apply only if you have practical experience with: Python Telegram Bot API aiogram FastAPI PostgreSQL AsyncIO LLM APIs Docker Experience with speech-to-text APIs, subscription systems, RAG, Redis, and production deployment is a plus. Questions for Applicants Please include the following information in your proposal: Examples of Telegram bots you have developed. Examples of LLM integrations you have implemented. Your suggested architecture for this project. Which LLM provider you recommend and why. How you would control token usage and API costs. Your estimated development timeline. Your fixed-price estimate or hourly rate. Which functionality you would include in the first MVP