English | Русский

Telegram OCR Bot

A powerful Telegram bot that uses Tesseract or Yandex Vision to transcribe text from images. Built with Aiogram 3, asynchronous SQLite, and packaged for easy deployment with Docker.

---

Table of Contents

• Highlights
• Quick Start (Docker Compose)
• Installation from Source
• Configuration
• Bot Management
• Contributing
• License

✨ Highlights

• 🚀 Multiple OCR Engines: Supports local processing with Tesseract and powerful cloud-based recognition with Yandex Vision.
• ⚡️ Asynchronous: Built on asyncio and aiogram for high performance and responsiveness.
• 💾 Persistent Storage: Uses SQLite via aiosqlite to asynchronously store user data, settings, and usage statistics.
• ⚙️ Flexible Limits System: Easily configure daily, weekly, and monthly usage limits for users.
• 🐳 Docker-Ready: Optimized for one-command deployment using Docker Compose.
• 🔧 Modern Tooling: Uses uv for package management and ruff for linting and formatting, ensuring code quality.

🚀 Quick Start (Docker Compose)

This is the recommended way to run the bot for production.

1. Create a Project Directory: Create a new directory and navigate into it.

2. Create docker-compose.yml: Create a file named docker-compose.yml with the following content:

   version: '3.8'
   
   services:
     ocr-bot:
       image: lowara1243/ocr-bot:1.1
       container_name: telegram_ocr_bot
       restart: always
       env_file:
         - .env
       environment:
         - DATA_DIR=/app/data
       volumes:
         - ./data:/app/data
       tty: true

   Note: The bot will automatically create the data directory and its subdirectories (database, logs, images) for persistent storage.

3. Configure the Bot: Create a .env file in the same directory. At a minimum, you must provide your BOT_TOKEN. See the Configuration section for a full list of variables.

4. Run the Bot:

   docker-compose up -d

The bot will start, create necessary files, and connect to Telegram.

🛠️ Installation from Source

Click to expand for manual installation instructions

1. Clone the Repository:

   git clone https://github.com/Lowara1243/ocr-bot.git
   cd ocr-bot

2. Install Dependencies: You will need tesseract-ocr installed on your system.

   • Ubuntu/Debian: sudo apt-get install tesseract-ocr tesseract-ocr-eng tesseract-ocr-rus
   • Arch Linux: sudo pacman -S tesseract tesseract-data-eng tesseract-data-rus
   • macOS: brew install tesseract
   • Windows: Download Installer

   We recommend using uv for Python package management.

   # Will create .venv and install all dependencies from pyproject.toml
   uv pip install -e .

3. Configure the Bot: Copy the example configuration file and edit it with your settings.

   cp .env.example .env
   nano .env

4. Run the Bot:

   python -m src.ocr_bot.main

⚙️ Configuration

To configure the bot, create a .env file in the project's root directory. The easiest way is to copy the example file:

cp .env.example .env

Then, open .env in your editor and adjust the settings.

Variable	Description	Required
BOT_TOKEN	Your Telegram bot token from @BotFather.	Yes
ADMIN_ID	Your Telegram User ID (admin has no limits).	No
DEFAULT_OCR_ENGINE	Default OCR engine to use (tesseract or yandex).	No
ENABLED_OCR_ENGINES	Comma-separated list of enabled engines (e.g., tesseract,yandex).	No
YANDEX_CLOUD_API_KEY	API key for Yandex Cloud Vision API.	No
YANDEX_CLOUD_FOLDER_ID	Folder ID for Yandex Cloud Vision API.	No
RATE_LIMIT_DAILY	Daily request limit (integer).	No
RATE_LIMIT_WEEKLY	Weekly request limit (integer).	No
RATE_LIMIT_MONTHLY	Monthly request limit (integer).	No
LOG_LEVEL	Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL.	No
LOG_FILE	Path to the log file (leave empty to log to console only).	No
DATABASE_FILENAME	Filename for the SQLite database (defaults to ocr_bot.db).	No
TESSERACT_CMD_PATH	Full path to the tesseract executable if not in the system PATH.	No
DEFAULT_OCR_LANGUAGE	Default OCR language (eng, rus, eng+rus, etc.).	No
SUPPORTED_OCR_LANGUAGES	Comma-separated list of supported languages (for Tesseract).	No
OCR_LOG_PREVIEW_LENGTH	Number of characters to preview from transcribed text in logs.	No

🚦 Bot Management

Basic commands for managing the bot's Docker container.

• View logs:

  docker-compose logs -f

• Stop the bot:

  docker-compose down

• Restart the bot:

  docker-compose restart

🤝 Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests, all are appreciated.

• Found a bug? Please use the Bug Report template to submit an issue.
• Have a feature idea? Open an issue to discuss it.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.