Official Telegram bot for the main Italian Python group and local sub-groups in Italy.

Electus — named after Neo's Latin epithet ("the chosen one") from The Matrix. The bot personality blends Matrix and Python themes, guiding users through verification and community moderation in Italian.

• Welcome captcha: New members must read a rules file and send a secret command to the bot in private chat before they can post in the group
• Spam detection: Rate limiting and duplicate message detection with automatic deletion
• Moderation: Ban, mute, and report commands (admin-only for ban/mute)
• Database abstraction: In-memory storage by default; persistent database can be added later

• Python 3.14+
• UV package manager

1. Install UV if needed:

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install dependencies:

   uv sync

3. Copy the environment template and configure:

   cp .env.example .env
   # Edit .env and set TELEGRAM_BOT_TOKEN

4. (Optional) Set the bot name and description in @BotFather:

   • /setname → Electus
   • /setdescription → Guardiano della comunità Python Italia

5. If using PostgreSQL (DATABASE_URL set), create the schema:

   psql "$DATABASE_URL" -f schema.sql

6. Run the bot:

   uv run python-italy-bot
   # or: uv run python -m python_italy_bot.main

Start the bot:

uv run python-italy-bot

The bot starts polling for updates. You should see:

INFO - Starting bot...
INFO - Application started

Stop with Ctrl+C.

• Ban: /ban @username, /ban user_id [reason], or reply to a message with /ban [reason]
• Unban: /unban @username, /unban user_id, or reply to user's message
• Mute: /mute @username [minutes] [reason], or reply to message. Omit minutes for indefinite mute.
• Unmute: /unmute @username, /unmute user_id, or reply to user's message
• Report: Reply to the offending message with /report [reason]
• Admin request: Type @admin or @admin [message] to notify admins (no reply needed)

New members must send the secret command in DM to the bot. Default: python-italy (configurable via CAPTCHA_SECRET_COMMAND). Send it as plain text in a private chat with the bot.

1. Add the bot to a group: Make the bot an admin so it can restrict members and ban/mute users.

2. Test captcha:

   • Join the group with a test account (not admin).
   • You should be restricted (read-only).
   • Open a private chat with the bot and send the secret command (e.g. python-italy).
   • You should be unrestricted in the group.

3. Test moderation (as admin):

   • /ban @username or reply to a message with /ban [reason]
   • /unban @username to unban
   • /mute @username 60 to mute for 60 minutes
   • /unmute @username to unmute

4. Test report (as any member):

   • Reply to a message with /report spam (or any reason).

5. Test @admin (as any member):

   • Type @admin or @admin need help to request admin intervention (no reply needed).

src/python_italy_bot/
├── main.py           # Entry point, Application setup
├── config.py         # Settings from env
├── handlers/         # Telegram update handlers
│   ├── welcome.py    # New member + captcha flow
│   ├── moderation.py # Ban, mute, report commands
│   └── spam.py       # Spam detection
├── services/         # Business logic
│   ├── captcha.py    # Captcha verification
│   ├── spam_detector.py
│   └── moderation.py
├── db/               # Persistence abstraction
│   ├── base.py       # Repository interface
│   ├── models.py     # Domain models
│   └── in_memory.py  # In-memory implementation
└── assets/           # Captcha/rules file

1. User joins group → Bot restricts them (read-only)
2. Bot sends welcome message with instructions
3. User reads the rules file and finds the secret command
4. User sends the secret command to the bot in private chat
5. Bot verifies and removes restrictions in the group

MIT