How icherniukh/mr-prompter-bot works
1. This repository actually contains two related execution paths:
- a legacy Telegram bot for batch watermark/overlay removal, implemented under src/
- a newer standalone Gemini 2.5 Flash Image tool under scripts/, which the README says is the current recommended path
2. The legacy bot is the main system architecture to diagram if you want the deployed service. Its entrypoint is src/main.py, which wires together configuration, persistence, Telegram handlers, and the image-editing engine.
3. The request flow in the legacy bot is:
user sends one or more images to Telegram → handlers.py groups and routes the batch → engine.py sends each image independently to an image-output model → cleaned images are returned to Telegram one-for-one.
Captions are ignored, and the instruction is fixed in code rather than user-provided.
4. The bot has a hard split between free-tier processing and user-owned processing:
- a host-provided OpenRouter key can be used for the first 25 images per user
- after that, the user must add their own OpenRouter key via /setup
- /model, /forget, /status, and /cancel manage that state
This free-tier limit is enforced atomically in the database so concurrent batches cannot over-grant slots.
5. Persistence is centered on SQLite via aiosqlite in src/database.py. The database stores per-user state such as:
- encrypted API key
- selected model
- cumulative free-image usage
- reservation/refund state for the free tier
The README indicates the encryption key is stored separately in data/secret.key, and the database file is locked down on disk.
6. The engine boundary is the external image-edit provider. In the legacy bot, src/engine.py uses httpx to call OpenRouter image-editing models, not a text-only LLM. The repo emphasizes that the task is image transformation, so the model must return edited images rather than textual descriptions.
7. Configuration is handled in src/config.py and .env. It controls:
- Telegram/OpenRouter credentials
- default model selection and model shortlist
- host free-tier availability
- runtime paths such as data/
The architecture depends on environment-driven deployment, especially for keys and model selection.
8. The standalone Gemini tool in scripts/gemini_25_free_watermark_remover.py is a separate local pipeline. It processes files/folders directly instead of going through Telegram, and uses prompt files from prompts/ such as conservative-watermark-removal.txt. That path is simpler: local inputs → Gemini API → cleaned images on disk.
9. The scripts/evaluate_image_models.py utility suggests an evaluation loop around model choice. Combined with the prompts/ directory, this repo is set up not just as a bot, but as a model-comparison workspace for testing watermark-removal quality and tradeoffs.
10. Deployment is handled by run_bot.sh and deploy/mr-prompter-bot.service. The run script bootstraps a virtualenv and loads .env; the systemd unit is the server-side wrapper for the legacy Telegram bot. Operational logs are written under data/logs/ with rotation for postmortem analysis.
11. The test suite is architecture-relevant because it validates the key boundaries:
- configuration parsing
- database behavior, including the free-tier concurrency regression
- engine behavior for success and failure cases
- handler routing for free-tier exhaustion, unlimited own-key usage, and refund-on-failure
This indicates the system’s most important invariants are around state management and external API error handling.
12. In diagram terms, the main components are: Telegram client/UI, handler layer, SQLite-backed user state store with encrypted secrets, OpenRouter image-edit API, and the standalone Gemini local tool as an alternate execution path. The key data flow is “batch image upload → per-image edit call → per-image response,” with quota and key-management checks happening before and after each edit.
Main entry points: main.py Main · handlers.py Handlers · engine.py Engine · database.py Database
Components 15
Legacy Telegram Bot
Deployed batch image-removal service under src/
- Main · Wires configuration, handlers, database, and engine for the Telegram bot
src/main.py - Handlers · Groups batch uploads, routes commands, and manages quota/key state transitions
src/handlers.py - Engine · Calls external image-edit models and returns edited images one-for-one
src/engine.py - Database · Async SQLite persistence for user state, free-tier accounting, and encrypted secrets
src/database.py - Config · Loads environment-driven settings, model shortlist, paths, and credentials
src/config.py - Telegram · User-facing messaging and image upload interface
- OpenRouter · External provider used for the legacy bot's per-image transformations
- Data Files · Persistent on-disk data such as logs, database, and secret key material
data
Standalone Tools
Local Gemini workflow and model evaluation utilities under scripts/ and prompts/
- Gemini Tool · Standalone file/folder workflow using Gemini 2.5 Flash Image
scripts/gemini_25_free_watermark_remover.py - Model Eval · Utility for comparing model quality and tradeoffs
scripts/evaluate_image_models.py - Prompts · Instruction files used by the standalone tool and evaluation workflows
prompts - Gemini API · External model endpoint used by the standalone local pipeline
- Local Files · Direct file and folder inputs and on-disk cleaned outputs
Deployment
Runtime bootstrap and systemd service wrapper
- Run Script · Bootstraps the virtualenv and loads .env for local/server execution
run_bot.sh - Systemd Unit · Server-side service definition for the legacy Telegram bot
deploy/mr-prompter-bot.service
Connections 20
- Telegram → Main: messages · Users send batches and commands into the bot entrypoint
- Main → Config: load settings · Initializes runtime from environment and path configuration
- Main → Handlers: register · Wires Telegram update handling and command routes
- Main → Database: open store · Creates the persistence layer used by handlers and quota logic
- Main → Engine: wire client · Connects the editing engine into the request flow
- Handlers → Database: check quota · Reads and updates user state, key ownership, and reservations
- Handlers → Engine: edit batch · Sends each image independently for transformation
- Handlers → Telegram: reply images · Returns cleaned images one-for-one to the user
- Engine → OpenRouter: image edit · Calls the external provider for edited image outputs
- Database → Data Files: persist · Stores SQLite data, encrypted secrets, and logs on disk
- Config → Data Files: paths · Defines runtime directories such as data/ and logs
- Run Script → Main: launch · Bootstraps and starts the legacy bot process
- Systemd Unit → Run Script: service start · Server wrapper that invokes the bootstrap script
- Gemini Tool → Local Files: read/write · Processes local files and writes cleaned images back to disk
- Gemini Tool → Prompts: load prompt · Uses prompt files to steer image-removal behavior
- Gemini Tool → Gemini API: generate · Calls Gemini 2.5 Flash Image for local image editing
- Model Eval → Prompts: compare prompts · Supports model and prompt comparison workflows
- Model Eval → Gemini API: benchmark · Runs evaluation against image model endpoints
- Database → Handlers: state result · Returns quota and ownership state for routing decisions
- Engine → Handlers: success/fail · Propagates image-edit outcomes for refund and retry handling