{"id":50547337,"url":"https://github.com/icherniukh/mr-prompter-bot","last_synced_at":"2026-06-04T00:01:33.619Z","repository":{"id":361216794,"uuid":"1253591917","full_name":"icherniukh/mr-prompter-bot","owner":"icherniukh","description":"Mr Prompter — Telegram bot that removes watermarks, overlays, logos and labels from batches of images using OpenRouter image models (gemini-2.5-flash-image). Free 25-image tier + bring your own key.","archived":false,"fork":false,"pushed_at":"2026-05-29T16:16:12.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T18:07:40.338Z","etag":null,"topics":["ai","bot","gemini","image-editing","openrouter","python","telegram","watermark-removal"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icherniukh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-29T16:10:36.000Z","updated_at":"2026-05-29T16:16:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/icherniukh/mr-prompter-bot","commit_stats":null,"previous_names":["icherniukh/mr-prompter-bot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/icherniukh/mr-prompter-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icherniukh%2Fmr-prompter-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icherniukh%2Fmr-prompter-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icherniukh%2Fmr-prompter-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icherniukh%2Fmr-prompter-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icherniukh","download_url":"https://codeload.github.com/icherniukh/mr-prompter-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icherniukh%2Fmr-prompter-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33884734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bot","gemini","image-editing","openrouter","python","telegram","watermark-removal"],"created_at":"2026-06-04T00:01:32.572Z","updated_at":"2026-06-04T00:01:33.613Z","avatar_url":"https://github.com/icherniukh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mr Prompter — batch watermark / overlay removal bot\n\nA functional Telegram bot. Send it a batch of images and it returns the same\nimages with watermarks, logos, text overlays, captions and labels removed —\neach image processed independently. No prompt or instructions required.\n\n**Current path for friends (recommended):** Use the standalone Gemini 2.5 Flash Image tool below. No user keys, no 25-image limit, full fidelity.\n\n```mermaid\nflowchart LR\n    U([User]) -- sends images --\u003e B[Bot]\n    B -- free tier? --\u003e Q{free_used \u003c 25?}\n    Q -- yes --\u003e H[Host OpenRouter key]\n    Q -- no --\u003e K[User's own key /setup]\n    H \u0026 K -- image + fixed instruction --\u003e OR[OpenRouter image model]\n    OR -- cleaned image --\u003e B\n    B -- one cleaned image per input --\u003e U\n```\n\n## How it works\n\n1. A user sends one or more images (as photos, or as files for best quality).\n2. Each image is processed independently and the cleaned version is sent back —\n   so a batch of N images yields N cleaned images.\n3. The first **25 images per user** are processed on the host's shared\n   OpenRouter key (`HOST_OPENROUTER_KEY`). After that, the user runs `/setup`\n   to add their own OpenRouter key and continues with no limit.\n\nA single fixed instruction drives every call (see `REMOVAL_INSTRUCTION` in\n`src/engine.py`); the user never writes a prompt. Any image caption is ignored.\n\n## Why an image-output model\n\nRemoving a watermark means *returning a new, edited image* — not describing one.\nA plain text/vision LLM can only read an image, so this bot uses OpenRouter\n**image-output (editing) models**.\n\nCurrent shortlist (in `src/config.py` and `MODEL_SHORTLIST` env var) contains\nthe models we are actively evaluating for watermark/overlay removal quality.\n\n**Cost-effective recommendations** (as of late 2026 research):\n- `black-forest-labs/flux.2-klein-4b` — Currently one of the cheapest strong options.\n- `sourceful/riverflow-v2-fast` — Excellent speed/price balance.\n- `recraft/recraft-v4.1-utility` — Best control via `image_config.strength` for conservative edits that don't destroy real signage.\n\nThe more expensive models (Gemini Pro previews, GPT-5.4 Image, Grok Imagine, FLUX.2 Pro/Max) can be used when higher quality is required.\n\n**Important**: Real usage requires empirical testing. Only image-output / image-editing models are valid in the shortlist.\n\nA future lower-cost architecture may use a two-stage pipeline (cheap detection model → precise masked inpainting) instead of full image-to-image on every request.\n\n## Free tier\n\n- Counted **per user, for the lifetime of their record** (`free_used` column).\n- A slot is reserved atomically *before* processing (`claim_free_slot`), so a\n  batch processed concurrently can never exceed the cap.\n- If an image fails, the slot is **refunded** (`release_free_slot`) — failures\n  don't cost the user.\n- If `HOST_OPENROUTER_KEY` is unset, the free tier is disabled and users must\n  add their own key first.\n\n## Commands\n\n| Command   | What it does                                   |\n|-----------|------------------------------------------------|\n| `/start`  | What the bot does                              |\n| `/status` | Free images remaining / current model          |\n| `/setup`  | Add your own OpenRouter key, then pick a model |\n| `/model`  | Change the AI model                            |\n| `/forget` | Delete your stored key, model, and usage count |\n| `/cancel` | Cancel the current operation                   |\n\n## Security\n\n- User API keys are **Fernet-encrypted at rest**. The master key lives in\n  `data/secret.key` (mode 0400), separate from `.env`, and the SQLite file is\n  restricted to `0600`.\n- Pasted keys are deleted from the chat on a best-effort basis, and logs redact\n  anything matching an OpenRouter/OpenAI key pattern.\n\n## Quick start (Gemini 2.5 free tool — current recommended)\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\n# add your GEMINI_API_KEY (get from https://aistudio.google.com/app/apikey)\npython scripts/gemini_25_free_watermark_remover.py /path/to/images/\n```\n\nThe old Telegram bot (OpenRouter-based) is kept as dead code for now.\n\nFor the legacy Telegram bot: see \"Running in Production\" below.\n\n## Running in Production\n\n### Using the run script (recommended)\n\nA convenience script is provided:\n\n```bash\nchmod +x run_bot.sh\n./run_bot.sh\n```\n\nThis script:\n- Activates the virtual environment (if `.venv` or `venv` exists)\n- Loads variables from `.env`\n- Starts the bot\n\n### Systemd autostart (recommended for servers)\n\n1. Copy the example service file:\n\n   ```bash\n   sudo cp deploy/mr-prompter-bot.service /etc/systemd/system/\n   ```\n\n2. Edit it to match your setup (especially `User` and `WorkingDirectory`):\n\n   ```bash\n   sudo nano /etc/systemd/system/mr-prompter-bot.service\n   ```\n\n3. Enable and start:\n\n   ```bash\n   sudo systemctl daemon-reload\n   sudo systemctl enable mr-prompter-bot\n   sudo systemctl start mr-prompter-bot\n   ```\n\n4. Useful commands:\n\n   ```bash\n   sudo systemctl status mr-prompter-bot\n   sudo journalctl -u mr-prompter-bot -f\n   sudo systemctl restart mr-prompter-bot\n   ```\n\nThe service is configured to restart automatically on failure.\n\n### Error Telemetry\n\nAll uncaught errors are permanently logged to disk for future analysis:\n\n- Gemini 2.5 free tool: `data/logs/gemini_free_errors.log`\n- Legacy Telegram bot: `data/logs/errors.log`\n\nBoth use rotating file handlers (5 MB files, several backups). These files are very useful for post-mortem analysis when something goes wrong in production.\n\n### Running the Gemini 2.5 free tool\n\n```bash\n# One-shot\npython scripts/gemini_25_free_watermark_remover.py photo.jpg folder/ --prompt-file prompts/conservative-watermark-removal.txt\n\n# With the run script (loads .env)\n./run_bot.sh --gemini /path/to/images/\n# (edit run_bot.sh if you want it to default to Gemini mode)\n```\n\nFor systemd, point ExecStart at a small wrapper that calls the Gemini script (or run it manually / via cron).\n\n### Running the legacy Telegram bot (OpenRouter)\n\nUse the sections below (run_bot.sh + systemd still point at `src.main`).\n\n## Stack\n\n- Python 3.12+, `python-telegram-bot` 21\n- `httpx` for the OpenRouter image-edit calls\n- `aiosqlite` for async SQLite, `cryptography` (Fernet) for key encryption\n- Default model: `google/gemini-2.5-flash-image` (overridable via env)\n\n## Tests\n\n```bash\nsource .venv/bin/activate\npip install -r requirements-dev.txt\npytest\n```\n\nCovers the database layer (including a concurrency regression proving the free\ntier can't be over-granted), the OpenRouter engine (success, missing-image, HTTP\nand network errors), config parsing, and the handler routing (free-tier\nexhaustion, own-key unlimited, failure refund, no-host-key).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficherniukh%2Fmr-prompter-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficherniukh%2Fmr-prompter-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficherniukh%2Fmr-prompter-bot/lists"}