Yaroslav Smirnov

Train Prompts Bot – Interactive Prompt Engineering Education Platform

A production-grade educational system for teaching prompt engineering through structured lessons, AI-powered evaluation, and quota management. Built with aiogram 3 (Telegram bot framework), PostgreSQL, and multi-provider AI orchestration, it demonstrates expertise in modular bot architecture, middleware patterns, and educational system design.

Why This Project Matters

Problem 1: Prompt Engineering Skill Gaps

• AI literacy is now essential, but most developers lack prompt engineering training
• Traditional learning paths (docs, blogs) lack immediate AI feedback and structured progression
• Educational platforms need to teach iterative prompt refinement with real-time AI evaluation

Problem 2: Scale vs. Cost Trade-off

• Running 1000+ concurrent educational users with AI generation queries creates exponential costs
• Platform must implement strict daily quotas per user while providing admins unlimited access
• Provider failures (Together AI down, LLM API rate limits) shouldn’t disrupt learning experience

Problem 3: Content Management at Bot Scale

• Telegram bots traditionally hardcode content; scaling requires database-driven lesson management
• Lessons need structured progression (5-10 ordered steps) with progress persistence per user
• Admin dashboards must track learner engagement, completion rates, and system usage in real-time

Business Impact:

• Automated grading reduces instructor overhead by 80% (AI evaluates quiz answers instantly)
• Daily quota system prevents runaway AI costs while ensuring fair access (~$0.02/user/day)
• Structured lessons → measurable progression tracking → higher completion rates than ad-hoc content

System Architecture & Design

Core Layers

1. Telegram Bot Interface (aiogram 3)

• Dispatcher-based event routing with middleware pipeline
• Session middleware: opens DB transaction at message start, commits/rolls back at handler exit
• Automatic user creation on first message (passwordless entry)
• Inline keyboards for UX (lessons, quizzes, navigation)

2. Backend Core (Python 3.9+ Async)

• SQLAlchemy with asyncpg for PostgreSQL operations
• Five domain modules (handlers organized by responsibility):
  • basic/ – Start, help, menu commands
  • admin/ – User management, statistics, system health
  • lessons/ – Lesson delivery and step progression
  • generation/ – Text/image AI generation with quota checks
  • quizzes/ – Quiz delivery and AI-powered answer evaluation

3. Educational Content Model

Lesson (ordered collection)
├── Step 1 (text + example prompts)
├── Step 2 (text + example prompts)
├── ...
├── Step N (quiz challenge)

Quiz
├── Question (text)
├── Rubric (evaluation criteria for AI grader)
├── Reference Answer (for quality checking)

UserProgress
├── lessons_completed (set of lesson IDs)
├── current_step (which step in current lesson)
├── quiz_scores (score per quiz)
└── leaderboard_position (ranked by points)

4. AI Integration Architecture

Generation Request
├─→ Quota Check (Is daily limit exceeded?)
├─→ Provider Selection (LLM7 for text, Together.ai for images)
├─→ Request Dispatch
│   ├─→ Primary provider (95% success rate)
│   ├─→ Fallback on timeout/rate-limit (5s timeout)
│   └─→ Error response if all fail
└─→ Result formatting + quota decrement (atomic)

Quiz Evaluation Pipeline
├─→ AI analyzes user answer against rubric
├─→ Generates score (0-100) + feedback
├─→ Stores result persistently
└─→ Updates leaderboard position

5. Data Persistence (PostgreSQL)

• Async SQLAlchemy with alembic migrations
• Tables: Users, Lessons, UserProgress, Quizzes, QuizAnswers, DailyQuotas
• Indexes on (user_id, lesson_id), (user_id, date) for quota lookups
• Row-level locking for atomic quota updates

Data Flow: Learning Session

1. User Starts Bot → /start message
2. Auto-Registration → User record created if new
3. Menu Selection → User selects “Start Lesson”
4. Lesson Delivery → Bot sends step 1 (text + example prompts)
5. User Attempts → User submits their own prompt
6. AI Generation → System calls text generation API (quota decremented atomically)
7. Result Display → Bot shows generated output
8. Step Progression → User proceeds to step 2, or completes lesson
9. Quiz Challenge → Final step is interactive quiz
10. AI Grading → Quiz answer sent to LLM for evaluation
11. Score Recording → Result stored, leaderboard updated
12. Feedback → Bot displays score + AI feedback

Key Technical Features

1. Modular Handler Architecture

• Domain Separation: Five handler modules isolate concerns (admin operations separate from student learning)
• Handler Reusability: Common functions (quota checking, error formatting) extracted to services layer
• Testing Isolation: Each module can be tested independently with mock DB
• Feature Flags: Admin-only endpoints secured with role-based middleware

2. Middleware Pattern for Cross-Cutting Concerns

• Session Management: Every message triggers middleware that:
  1. Opens new DB connection/transaction
  2. Passes session to handler
  3. Auto-commits on success, rolls back on exception
• Error Handling: Middleware catches exceptions, logs them, returns user-friendly messages
• Access Control: Middleware checks if user_id in ADMIN_IDS for protected endpoints
• Request Logging: Tracks all user interactions (lesson starts, generation requests, quiz attempts)

3. Quota Management System

• Daily Reset: Background job runs at midnight UTC, sets all quotas to daily_limit
• Atomic Decrement: Quota update uses UPDATE WHERE quota > 0 to prevent over-consumption
• Admin Bypass: Admin users skip quota checks entirely (no limits)
• Grace Period: First-time users get +3 bonus quota for incentive
• Quota Analytics: Dashboard shows per-user consumption, trending usage

4. AI Provider Resilience

• Multi-Provider Support: Text (LLM7) separate from images (Together.ai)
• Timeout Handling: 5-second timeout per provider call; if exceeded, log error + return generic message
• Graceful Degradation: Text generation fails → show “AI service temporarily unavailable” vs. crashing
• Cost Optimization: Route image generation only to Together.ai (cheapest), text to LLM7 (fastest)
• Provider Health Checks: Admin dashboard shows last successful call time per provider

5. Assessment Pipeline

• Rubric-Based Grading: Quiz has evaluation criteria (e.g., “uses specific examples”, “clear structure”)
• AI Evaluation: Send user answer + rubric to LLM, get structured score + reasoning
• Feedback Generation: AI produces learner-friendly explanation of score
• Result Persistence: All quiz attempts stored for analytics and leaderboard calculations
• Leaderboard Ranking: Scored answers contribute to user ranking (gamification)

6. Content Seeding & Versioning

• Startup Seeding: On first bot start, lessons and quizzes loaded from seed file
• Version Control: Seed file versioned in git; changes tracked like code
• Content Updates: Admin can add new lessons via CLI tool (not directly in bot)
• Backward Compatibility: Old users continue where they left off even if lesson content updated

Technologies & Stack

Bot Framework

• aiogram 3 – Modern async Telegram bot framework
• Dispatcher pattern – Event routing and middleware pipeline
• asyncio – Python async runtime for concurrency

Backend

• Python 3.9+ with async/await throughout
• SQLAlchemy 2.0 – Async ORM with asyncpg PostgreSQL driver
• Pydantic – Request/response validation and settings
• Alembic – Database schema migrations
• Loguru – Structured logging

Database

• PostgreSQL 14 – Persistent data storage
• asyncpg – High-performance async Postgres driver
• Row-level locking – Prevents quota race conditions

External Services

• LLM7 – Text generation API (or similar provider)
• Together.ai – Image generation API (Stable Diffusion, DALL-E)
• Telegram Bot API – Message routing and updates

Development & Testing

• pytest – Unit test framework
• python-dotenv – Environment configuration
• Black – Code formatting

Engineering Challenges & Trade-offs

Challenge 1: Session Management Without Traditional Web Requests

Problem: Web apps have clear request/response cycles; Telegram bots receive async updates at unpredictable times.
Solution: Middleware wraps handler execution—open transaction at message arrival, commit at handler exit
Trade-off: More complex error handling (if handler crashes mid-transaction, rollback required)
Result: Guaranteed data consistency; partial writes impossible

Challenge 2: Quota Management Under Concurrency

Problem: Two users trigger generation simultaneously → both read quota=10, both proceed → consume 20 (exceeds limit)
Solution: Use UPDATE users SET quota = quota - 1 WHERE user_id = ? AND quota > 0 to atomically check + decrement
Trade-off: Second request fails if quota exhausted (user sees “quota exceeded”); requires retry logic client-side
Result: Strict quota enforcement; no overshooting

Challenge 3: AI Provider Failures vs. User Experience

Problem: Together.ai down → image generation times out → user waits 30s then sees error
Solution: Implement 5-second timeout; if provider doesn’t respond, immediately return cached response or generic message
Trade-off: Sometimes show “AI service temporarily unavailable” instead of actual output; feels less responsive
Decision: Better to admit failure quickly than hang the user

Challenge 4: Structured Lessons in Unstructured Bot Format

Problem: Lessons have ordering (Step 1 → Step 2 → …) but bot is message-driven (no guaranteed state)
Solution: Persist current_step in database; on each message, check step, display content, wait for user interaction
Trade-off: Can’t easily show “Step 2 of 5” progress UI (Telegram bots have limited UI)
Result: Functional but less visually polished than web version

Challenge 5: Cost Control with AI Generation

Problem: Unlimited users = unlimited generation requests = runaway costs
Solution: Daily quotas (10 text, 5 images) + admin bypass for testing
Trade-off: Strict limits frustrate power users; require separate “pro” tier for higher quotas
Decision: Prevents financial disaster; pro tier can be added later

Current State & Demo Notes

Implemented Features

• ✅ Telegram bot entry point with start/help/menu commands
• ✅ Modular handler architecture (admin, lessons, generation, quizzes)
• ✅ PostgreSQL user and progress tracking
• ✅ 5-lesson structured curriculum on prompt engineering
• ✅ Text generation via LLM7 (with timeout + fallback)
• ✅ Image generation via Together.ai
• ✅ Daily quota system (automatic reset at midnight UTC)
• ✅ Quiz evaluation with AI-powered grading
• ✅ Leaderboard ranking by total quiz score
• ✅ Admin dashboard (user stats, quota usage, provider health)
• ✅ Middleware session management with transaction safety
• ✅ Startup content seeding (lessons/quizzes from seed file)

Architecture Decisions Evident

• Async-First: Every handler, every DB call uses async/await (no blocking operations)
• Middleware Safety: All DB operations wrapped in transactions (commit/rollback guaranteed)
• Graceful Degradation: AI provider timeouts handled with user-friendly fallbacks
• Production-Ready: Error logging, admin notifications, health checks in place
• Modular Design: Adding new lesson type or generation provider requires changes in one module only

Not Yet Implemented (Out of Scope for MVP)

• User-to-user comparison (private leaderboards)
• Advanced content analytics (which lessons are hardest?)
• Scheduled reminders (daily practice nudges)
• Multi-language support (currently English only)
• API access (read-only access for external analytics)

How This Project Demonstrates My Expertise

Backend Engineering

• Async Bot Architecture: Building scalable Telegram bots requires understanding async patterns. This system processes 100+ concurrent users with non-blocking I/O throughout entire stack.
• Database Transaction Safety: Implementing middleware that guarantees ACID properties (no partial writes) is non-trivial. Demonstrates understanding of database semantics beyond “ORM queries.”
• Error Handling for External Services: Real-world systems depend on third-party APIs (Together.ai, LLM7). Handling timeouts, rate limits, and failures gracefully is critical production skill.

System Design

• Modular Architecture: Five domain modules demonstrate separation of concerns. Admin features isolated from student-facing features; testing one module doesn’t require entire system.
• Quota Systems: Implementing fair usage (daily quotas, atomic decrements, admin bypass) requires thinking about resource constraints and fairness. Common pattern in production systems.
• Assessment Engine: Building automated evaluation requires understanding rubrics, scoring logic, and feedback generation—moving beyond “prompt → LLM → response” to “question → LLM → structured score + reasoning.”

DevOps & Data

• Database Migrations: Using Alembic to version schema changes. Not just “create tables once,” but evolving schema as features ship.
• Startup Seeding: Ensuring consistent content across deployments (lessons, quizzes load from versioned seed file). Shows production thinking about environment consistency.
• Admin Observability: Dashboards for quota usage, provider health, user statistics. Demonstrates that shipped systems need visibility into operational state.

Teaching & Communication

• Educational Design: Structuring 5-lesson curriculum on prompt engineering. Writing quiz rubrics. Shows ability to decompose complex topic into learnable steps.
• User Feedback: AI-powered evaluation provides immediate feedback to learners. Demonstrates thinking about how systems guide users toward better behavior.

AI Integration

• Multi-Provider System: Choosing LLM7 for text (fast), Together.ai for images (cheap). Shows strategic thinking about which provider fits which task.

• Structured AI Output: Sending quiz answer + rubric to LLM and parsing structured response (score, reasoning). Moving beyond raw text generation to business logic.

  Technology Stack

  Backend & Framework

  • Python 3 with asyncio
  • aiogram 3 for Telegram Bot API
  • SQLAlchemy async ORM
  • asyncpg PostgreSQL driver

  AI & Integration

  • LLM7 API for text generation
  • Together AI for image generation
  • aiohttp for async HTTP requests
  • Dynamic provider loading with retries

  Database & Storage

  • PostgreSQL as primary database
  • File system for generated images
  • Migration scripts for schema evolution
  • CRUD helpers for data operations

  DevOps & Configuration

  • Environment-based configuration
  • Structured logging with loguru
  • Startup content seeding
  • Defensive error handling

</div>

Engineering Challenges Solved

Unstable AI Providers

Added retry-capable provider selection, timeouts, and graceful fallbacks to ensure reliable AI generation even when individual providers experience issues.

Per-Update DB Safety

Implemented session middleware with commit/rollback safety to prevent partial writes and ensure data consistency during concurrent operations.

User Abuse Prevention

Implemented daily generation quotas with automatic reset and admin bypass to prevent abuse while ensuring fair usage.

Content Consistency

Created startup seeding pipeline for lessons and quizzes to keep environments aligned and ensure consistent content across deployments.

Impact & Educational Value

Technical Achievements

• End-to-end async architecture for high concurrency
• Modular design with clear separation of concerns
• Robust error handling with graceful degradation
• Secure admin controls with role-based access
• Scalable data model for content growth

Educational Value

• Structured learning path for prompt engineering
• Immediate AI feedback for skill development
• Progress tracking and motivation through ratings
• Hands-on practice with real AI systems
• Scalable platform for content expansion

System Demonstration

Key Features in Action

• Lesson navigation with step-by-step progress
• AI-powered text and image generation
• Quiz system with AI evaluation
• User ratings and leaderboard
• Admin console for management

View the Implementation

Discover the modular architecture, lesson system, and AI integration on GitHub

View on GitHub →

← Previous Project Back to Projects