README.md

metadata

title: AI Quiz Bot
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

🧠 AI Quiz Bot - Telegram Quiz Generator

A powerful Telegram bot that converts images, PDFs, or text into interactive multiple-choice quiz questions using Ollama Cloud API.

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Usage
• Architecture
• API Integration
• Error Handling
• Troubleshooting

🎯 Overview

The AI Quiz Bot is a Telegram bot that automates the creation of quiz questions from various content sources:

• 📸 Images: Extract text from screenshots, photos, and scanned documents
• 📄 PDFs: Process PDF documents and extract text
• ✍️ Text: Generate quizzes directly from typed text

The bot uses Ollama Cloud API to:

1. Analyze images and extract text using vision models
2. Generate intelligent, well-formatted multiple-choice questions using chat models

All questions are delivered as interactive Telegram polls with the correct answer marked.

✨ Features

Core Functionality

• ✅ Multi-Format Support: Images (JPG, PNG, WebP), PDFs, and plain text
• ✅ Customizable Question Count: 1-20 questions per request
• ✅ Intelligent Question Generation: AI-powered, contextual questions
• ✅ Interactive Polls: Each question as a Telegram poll with correct answer
• ✅ Multiple Languages: Arabic, English, and other languages
• ✅ Cloud-Based: Uses Ollama Cloud API (no local installation needed)

User Experience

• 🚀 Easy to Use: Simple commands (/start, /help)
• 📍 Progress Feedback: Real-time status messages
• 🎨 Friendly Interface: Arabic instructions and messages
• ⏱️ Asynchronous Processing: Non-blocking operations
• 🔄 Error Handling: Graceful error messages and recovery

🛠️ Prerequisites

System Requirements

• Python 3.9+
• Internet connection (for Ollama Cloud API)
• Telegram Bot Token (from @BotFather)
• Ollama Cloud API Key and Host

Software Dependencies

• python-telegram-bot - Telegram bot framework
• PyPDF2 - PDF text extraction
• httpx - Async HTTP client for API calls
• python-dotenv - Environment variable management

📦 Installation

Step 1: Clone/Download Project

cd c:\Users\mohamed\Desktop\Getting_Huge_Again\aiquiz

Step 2: Create Virtual Environment (Recommended)

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Create .env File

# Copy the template
copy .env.example .env   # Windows
cp .env.example .env     # Linux/Mac

Step 5: Configure Environment Variables

Edit .env with your credentials (see Configuration section)

⚙️ Configuration

Environment Variables (.env file)

# Your Telegram bot token (from @BotFather)
TELEGRAM_BOT_TOKEN=7319290683:AAFpfIEGCZGOky3OOB2V-xcn8rq8pc7TEUQ

# Ollama Cloud API endpoint
OLLAMA_HOST=https://ollama.com

# Ollama API authentication key
OLLAMA_API_KEY=830f2fd6fedc491ba49c91a0709c94d9.4Z84I1pRSwd8iPDT1J4Tfu6c

# Vision model for image analysis
VISION_MODEL=ministral-3:8b

# Chat model for quiz generation
CHAT_MODEL=ministral-3:14b

Getting Your Credentials

Telegram Bot Token:

1. Open Telegram and search for @BotFather
2. Type /newbot
3. Follow the prompts
4. Copy the token and paste in .env

Ollama API Credentials:

1. Visit https://ollama.com
2. Go to account settings → API keys
3. Create a new API key (copy the full key)
4. Get your API host URL (usually https://ollama.com)
5. Add both to .env

🚀 Running the Bot

python bot.py

The bot will start polling for messages from Telegram.

📱 Usage

User Commands

Command	Description
/start	Show welcome message with usage instructions
/help	Show FAQ and common questions

How to Use

Method 1: From Images

1. Send an image (screenshot, photo, etc.)
2. Add caption with number of questions (optional)
3. Bot extracts text and generates quiz

Method 2: From PDFs

1. Send a PDF file
2. Add caption with number of questions (optional)
3. Bot extracts text and generates quiz

Method 3: From Text

1. Send a text message
2. Optional: Start with a number on first line for question count
3. Bot generates quiz from text

Examples

• Send image + caption: 5 → Generates 5 questions
• Send PDF + caption: 10 → Generates 10 questions
• Send text starting with: 8\n → Generates 8 questions
• Default (no number): 5 questions generated

🏗️ Architecture

Project Structure

aiquiz/
├── bot.py                # Main bot code (see DEVELOPER_GUIDE.md)
├── requirements.txt      # Python dependencies
├── .env                  # Environment variables (DO NOT COMMIT)
├── .env.example          # Template for .env
├── .gitignore            # Git ignore file
├── README.md             # This file
├── DEVELOPER_GUIDE.md    # Detailed code explanation
└── ARCHITECTURE.md       # System design documentation

Data Flow

User Input (Image/PDF/Text)
        ↓
    Message Handler
        ├─→ handle_file()  [for images/PDFs]
        ├─→ handle_text()  [for text messages]
        └─→ Commands       [/start, /help]
        ↓
    File/Text Processing
        ├─→ extract_text_from_image()  [Vision API]
        ├─→ extract_text_from_pdf()    [PyPDF2]
        └─→ parse_num_questions()      [Parse input]
        ↓
    Quiz Generation
        └─→ generate_quiz_questions()  [Chat API → JSON]
        ↓
    Delivery
        ├─→ send_quiz_poll()           [Each question as poll]
        └─→ Completion message

🔌 API Integration

Ollama Cloud API Endpoints

Endpoint: POST {OLLAMA_HOST}/api/chat

Authentication: Bearer Token in Authorization header

Authorization: Bearer {OLLAMA_API_KEY}

Request Format

{
  "model": "model-name",
  "messages": [
    {"role": "system", "content": "system instructions"},
    {"role": "user", "content": "user message or image"},
  ],
  "stream": false,
  "format": "json"  # Optional, ensures JSON output
}

Response Format

{
  "message": {
    "role": "assistant",
    "content": "response content"
  }
}

For more details, see ARCHITECTURE.md

🛡️ Error Handling

Common Errors & Solutions

Error	Cause	Solution
getaddrinfo failed	Network/DNS issue	Verify internet and API URL
JSON Parse failed	Invalid API response	Check API key and retry
No text extracted	Unreadable file	Use clearer image/PDF
API timeout	Slow network	Increase timeout or retry
Invalid file type	Wrong format	Use JPG/PNG/PDF/text

Messages to Users

• ❌ "نوع ملف مش مدعوم!" - Unsupported file type
• ❌ "مش قادر استخرج نص كافي" - Text extraction failed
• ❌ "مش قادر اعمل اسئلة" - Quiz generation failed
• ❌ "النص قصير شوية!" - Text too short (min 20 chars)

🔧 Troubleshooting

Bot Won't Start

Error: TELEGRAM_BOT_TOKEN environment variable is not set!

Solution: Create .env file with your bot token

API Connection Failed

Error: getaddrinfo failed

Solutions:

1. Check internet connection
2. Verify OLLAMA_HOST is correct (https://ollama.com)
3. Verify OLLAMA_API_KEY is valid
4. Test API manually with curl

Poor Quiz Quality

Causes: Low-quality images, short text Solutions:

1. Use higher-resolution images
2. Provide more detailed text (minimum 20 characters)
3. Use clearer, well-formatted PDFs

Bot Responses Are Slow

Causes: Large files, slow internet, API processing Solutions:

1. Use smaller file sizes
2. Reduce number of questions
3. Be patient (can take 10-30 seconds)

📚 For Developers

See these files for detailed information:

• DEVELOPER_GUIDE.md - Code explanation, functions, and how to modify
• ARCHITECTURE.md - System design, API flow, data structures

🔐 Security Notes

• ⚠️ Never commit .env - Contains sensitive credentials
• 🔑 Keep API keys private - Don't share in code/issues
• 🛡️ Use HTTPS - All API communications are encrypted
• 📝 Validate input - All file types and sizes are checked

📄 License

MIT License - Feel free to use and modify!

---

Last Updated: February 2026
Bot Version: 1.0
API: Ollama Cloud API

🔧 Configuration

Variable	Description	Default
TELEGRAM_BOT_TOKEN	Your Telegram bot token	Required
OLLAMA_HOST	Ollama server URL	http://localhost:11434
VISION_MODEL	Model for image analysis	llava
CHAT_MODEL	Model for quiz generation	mistral

Recommended Models

For Vision (image analysis):

• llava - Good balance of speed and accuracy
• bakllava - Better for complex images
• llava:13b - Higher accuracy, slower

For Chat (quiz generation):

• mistral - Fast and good quality
• mixtral - Better quality, slower
• llama2 - Good alternative

🐛 Troubleshooting

"Connection refused" error

• Make sure Ollama is running: ollama serve

"Model not found" error

• Pull the required model: ollama pull <model_name>

Bot not responding

• Check your bot token is correct
• Ensure the bot is not blocked
• Check the console for error messages

Poor quiz quality

• Try a different/larger model
• Ensure the extracted text is clear and readable
• Use higher quality images

📁 Project Structure

aiquiz/
├── bot.py              # Main bot code
├── requirements.txt    # Python dependencies
├── .env.example        # Environment variables template
├── .env                # Your configuration (create this)
└── README.md           # This file

🔒 Security Notes

• Never commit your .env file with real tokens
• The .env file is in .gitignore by default
• Keep your Ollama instance secure if exposed to network

📄 License

MIT License - feel free to use and modify!