https://github.com/sudo-py-dev/lex-tg
A high-performance, modular Telegram management system built with Pyrogram and SQLAlchemy 2.0. Features deep localization (20+ languages), AI integration (Gemini/OpenAI), and a custom caching layer for maximum speed and reliability.
https://github.com/sudo-py-dev/lex-tg
high-performance mtproto pyrogram-bot telegram-bot-ai-assistant
Last synced: 20 days ago
JSON representation
A high-performance, modular Telegram management system built with Pyrogram and SQLAlchemy 2.0. Features deep localization (20+ languages), AI integration (Gemini/OpenAI), and a custom caching layer for maximum speed and reliability.
- Host: GitHub
- URL: https://github.com/sudo-py-dev/lex-tg
- Owner: sudo-py-dev
- Created: 2026-04-03T15:05:08.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-08T12:55:34.000Z (21 days ago)
- Last Synced: 2026-06-08T14:25:45.529Z (21 days ago)
- Topics: high-performance, mtproto, pyrogram-bot, telegram-bot-ai-assistant
- Language: Python
- Homepage:
- Size: 16.3 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.he.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 🌐 lex-tg: מנהל הקבוצות האולטימטיבי לטלגרם
[English](README.md) | [עברית](README.he.md)
**lex-tg** היא מערכת מודולרית מתקדמת לניהול קבוצות בטלגרם, שנבנתה במיוחד כדי לספק ביצועים מהירים ואמינות ללא פשרות. המערכת מבוססת על פרוטוקול **MTProto** ומשלבת טכנולוגיות אסינכרוניות מודרניות, מה שמאפשר שליטה מלאה בניהול הקבוצה תוך הקפדה על מהירות תגובה, תמיכה מלאה בריבוי שפות ובטיחות טיפוסים (Type Safety) מחמירה.
---
## ✨ יכולות מרכזיות
- 🛡️ **ניהול מתוחכם (Moderation)**: שליטה מלאה על חסימות, הרחקות והשתקות עם אפשרות להגדרת זמני תפוגה גמישים.
- 🔒 **נעילות דינמיות**: אפשרות לחסום באופן מיידי שליחת טקסט, מדיה, סטיקרים, קישורים או פקודות בוט.
- ⚡ **עוזר AI מובנה**: אינטגרציה חלקה עם Google Gemini ו-OpenAI למתן מענה חכם והפעלה אוטומטית בתוך הקבוצה.
- 🌊 **הגנה מהצפות ומתקפות (Flood & Raid)**: מנגנונים חכמים להגבלת קצב ושמירה על יציבות הקבוצה אל מול ספאם ומתקפות בוטים.
- 🌍 **לוקליזציה מלאה (i18n)**: תמיכה ביותר מ-20 שפות שונות המנוהלות דרך מערכת תרגום מרכזית אחת.
- 🎛️ **פאנל ניהול (Admin Panel) מתקדם**: ממשק משתמש אינטואיטיבי המבוסס על כפתורי תגובה (Callback) לניהול הגדרות הקבוצה בקלות.
- 🧩 **ארכיטקטורה 'שטוחה'**: מערכת פלאגינים אופטימלית וקלה לתחזוקה, שבה כל יכולת מרוכזת בקובץ אחד (Flattened).
---
## 🛠️ Stack טכנולוגי
| שכבה | טכנולוגיה |
| :---------------------- | :--------------------------------------------------------------------------------------- |
| **לקוח ליבה** | [Pyrogram](https://docs.pyrogram.org/) (Async MTProto) |
| **בסיס נתונים** | [PostgreSQL](https://www.postgresql.org/) (דרך [asyncpg](https://github.com/MagicStack/asyncpg)) |
| **מערכת מיגרציות** | [Alembic](https://alembic.sqlalchemy.org/) (מעברי סכמה אסינכרוניים) |
| **ניהול חבילות** | [uv](https://astral.sh/uv/) (מהירות שיא ובידוד סביבות עבודה) |
| **בטיחות טיפוסים** | [Mypy](https://mypy-lang.org/) (אכיפת סוגים קפדנית ללא פשרות) |
---
## 🚀 צעדים ראשונים
### 1. התקנת `uv`
הפרויקט עושה שימוש ב-`uv` לצורך ניהול מהיר של תלויות וסביבות וירטואליות מבודדות.
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 2. הגדרת הסביבה
שכפלו את הפרויקט וסנכרנו את התלויות:
```bash
uv sync
cp .env.example .env
```
> [!IMPORTANT]
> הקפידו למלא את המפתחות `API_ID`, `API_HASH`, ו-`BOT_TOKEN` בקובץ ה-`.env`. ניתן גם לשנות את שם הבוט הגלובלי (`BOT_NAME`) בתוך `src/config.py`.
### 3. הרצת הבוט
```bash
uv run bot
```
## 🛳️ פריסה (Deployment)
### אפשרות 1: Railway (מומלץ)
הדרך הקלה ביותר להריץ את הבוט 24/7.
1. לחצו על **New Project** בלוח הבקרה של Railway.
2. בחרו את המאגר (Repository) שלכם.
3. הוסיפו בסיס נתונים **PostgreSQL**.
4. עקבו אחר המדריך ב-[RAILWAY_GUIDE.md](RAILWAY_GUIDE.md) להגדרת משתנים ו-Volumes.
### אפשרות 2: Docker (עצמאי)
ודאו שמותקנים אצלכם Docker ו-Docker Compose בשרת (VPS).
1. **הגדרה**:
```bash
bash scripts/deploy_vps.sh
```
2. **ניהול**:
- צפייה בלוגים: `docker compose logs -f`
- עצירת הבוט: `docker compose down`
- הפעלת הבוט: `docker compose up -d`
---
## 🏗️ פיתוח ובקרת איכות
אנו מחויבים לסטנדרטים גבוהים במיוחד של איכות קוד.
### 🔍 בדיקות סטטיות (Static Analysis)
```bash
uv run lint # בדיקות לינטינג מהירות בעזרת Ruff
uv run fmt # עיצוב (Formatting) קוד אוטומטי
uv run typecheck # בדיקת סוגים קפדנית עם MyPy
```
### 🌐 ניהול תרגומים (Localization)
כלי התרגום שלנו שומר על סנכרון מלא בין כל השפות:
```bash
uv run translate # עדכון כל קבצי השפות מתוך en.json
```
### 🧪 בדיקות יחידה (Testing)
```bash
uv run test # הרצת סוויטת בדיקות מלאה (pytest-asyncio)
```
### 🗄️ מיגרציות בסיס נתונים
ודאו תמיד שסכמת בסיס הנתונים שלכם מעודכנת:
```bash
uv run migrate # עדכון לגרסת הסכמה האחרונה (alembic)
```
---
## 🏛️ מבנה הפרויקט
```text
├── src/
│ ├── core/ # אתחול הבוט וניהול הלקוח (Client)
│ ├── plugins/ # מערכת הפלאגינים המודולרית
│ │ ├── admin_panel/ # מנוע ההגדרות הוויזואלי
│ │ ├── ai_assistant/ # שכבת הבינה המלאכותית
│ │ ├── scheduler/ # ניהול משימות מתוזמנות
│ │ └── ... # מעל 30 פלאגינים בפורמט 'שטוח'
│ ├── repository/ # שכבת הנתונים (SQLAlchemy)
│ ├── locales/ # קבצי תרגום ובינלאומיות (.json)
│ └── utils/ # כלי עזר (הרשאות, מטמון, תרגום)
├── scripts/ # כלי עזר לאוטומציה ותרגום
└── tests/ # בדיקות מקיפות לכל חלקי המערכת
```
---
## 💎 סטטוס הפרויקט: הקשחה ושיפור ביצועים
Lex הועבר באופן מלא ל**שכבת מטמון פייתון טהורה**, מה שמאפשר לנו לוותר על תלויות חיצוניות דוגמת Redis, לצמצם את זמני השהייה ולפשט את תהליך הפריסה. אנו מקפידים על **100% כיסוי סוגים** בכל רכיבי הליבה.
> [!NOTE]
> אנחנו תמיד שמחים לתרומות קוד! אנא ודאו שכל בקשת מיזוג (PR) עוברת בהצלחה את הבדיקות `uv run lint` ו-`uv run typecheck` לפני ההגשה.