lex-tg is a state-of-the-art, modular Telegram group management system built for high-performance and absolute reliability. Leveraging the MTProto protocol and a modern asynchronous stack, lex-tg provides unparalleled control over group dynamics with a focus on speed, localization, and robust type safety.
- 🛡️ Advanced Moderation: Granular control over bans, kicks, and mutes with customizable expiry.
- 🔒 Dynamic Locks: Lock down text, media, stickers, URLs, or even bot commands instantly.
- ⚡ AI Assistant: Native integration with Google Gemini and OpenAI for intelligent group assistance and automated responses.
- 🌊 Flood & Raid Control: Intelligent rate-limiting and lockdown mechanisms to prevent group spam and malicious raids.
- 🌍 Deep Localization: Full multi-lingual support powered by a smart, centralized translation engine (20+ languages).
- 🎛️ Premium Admin Panel: Intuitive, callback-driven UI for effortless group configuration.
- 🧩 Flattened Architecture: Highly optimized, single-file plugin system for maximum maintainability.
| Layer | Technology |
|---|---|
| Core Client | Pyrogram (Async MTProto) |
| Database | SQLAlchemy 2.0 (Modern ORM with strict typing) |
| Caching | AsyncSnapshotCache (High-speed, Redis-less local cache) |
| Package Manager | uv (Extreme performance & isolation) |
| Type Safety | Mypy (Strict null-safety & guard patterns) |
Lex requires uv for lightning-fast dependency resolution and isolated environments.
curl -LsSf https://astral.sh/uv/install.sh | shClone the repository and sync the dependencies:
uv sync
cp .env.example .envImportant
Ensure you fill in your API_ID, API_HASH, and BOT_TOKEN in the .env file. You can also customize the BOT_NAME in src/config.py (default: lex-tg).
uv run botEnsure you have Docker and Docker Compose installed on your VPS.
- Setup:
bash scripts/deploy_vps.sh
- Manage:
- View logs:
docker compose logs -f - Stop bot:
docker compose down - Start bot:
docker compose up -d
- View logs:
If you prefer running without Docker:
- Copy the service file:
sudo cp lex-tg.service /etc/systemd/system/
- Enable and start:
sudo systemctl daemon-reload sudo systemctl enable lex-tg sudo systemctl start lex-tg - View logs:
journalctl -u lex-tg -f
We maintain rigorous standards for code quality and reliability.
uv run lint # Ultra-fast linting with Ruff
uv run fmt # Automatic code formatting
uv run typecheck # Strict type-checking with MyPyOur smart translation tool ensures all languages stay in sync:
uv run translate # Sync all locales from en.jsonuv run test # Comprehensive pytest-asyncio suite├── src/
│ ├── core/ # Bot initialization and core client
│ ├── plugins/ # Flattened modular feature sets
│ │ ├── admin_panel/ # UI-driven configuration engine
│ │ ├── ai_assistant/ # LLM integration layer
│ │ ├── scheduler/ # Background task management
│ │ └── ... # 30+ flattened plugin files
│ ├── repository/ # Data access layer (SQLAlchemy Models)
│ ├── locales/ # Internationalization schemas (.json)
│ └── utils/ # Hardened helpers (Permissions, Cache, i18n)
├── scripts/ # DevOps and localization automation
└── tests/ # Comprehensive test suites
Lex has been fully migrated to a pure Python caching layer, removing standard external dependencies like Redis to minimize latency and simplify deployment. We maintain 100% type-coverage for all core modules.
Note
Contributions are welcome! Please ensure all pull requests pass uv run lint and uv run typecheck before submission.