🇷🇺 РусЯзык — Telegram-бот по русскому языку

Умный помощник для школьников 5–9 класса с базой знаний из 50 000+ страниц, RAG-поиском и ИИ на базе Llama 3.3 70B

Авторы: Спиридонов Максим и Питишов Никита, 7 класс
Фестиваль: «Область ИИзменений», Московская область, 2025–2026
Бот: @rusyazyk_bot

---

✨ Возможности

Функция	Описание
✏️ Орфография	Проверка ошибок с объяснением правила
📖 Значение слова	Словари Ушакова, Ожегова, gramota.ru
🔍 Части речи	Полный разбор предложения
📊 Склонение	Все 6 падежей, ед. и мн. число
🧩 Морфемный разбор	Приставка / корень / суффикс / окончание
🤔 Объяснить правило	База 1659 правил + RAG по 50k страниц
📝 ОГЭ / ЕГЭ	Разбор заданий пошагово
✍️ Сочинение	План, аргументы, вывод
🔎 Поиск	Поиск по интернету + локальная база

---

🛠️ Технологии

• Python 3.11+
• python-telegram-bot — Telegram API
• Groq API (Llama 3.3 70B) — языковая модель
• SQLite + FTS5 — локальная база знаний (50k+ страниц)
• RAG — поиск по базе перед каждым ответом
• Selenium + Requests — краулер для сбора данных
• SQLite кэш — вечный кэш ответов (30 дней)
• Rate limiting — защита от спама (20 запросов/мин)

---

📁 Структура проекта

PythonProject/
├── bot.py          ← основной бот
├── crawler.py      ← краулер для сбора базы знаний
├── rules.json      ← база правил (1659 правил)
├── rusdb.db        ← локальная база знаний (создаётся краулером)
├── cache.db        ← кэш ответов (создаётся автоматически)
├── stats.json      ← статистика (создаётся автоматически)
└── README.md       ← этот файл

---

🚀 Установка и запуск

1. Клонировать репозиторий

git clone https://github.com/ВАШ_АККАУНТ/rusyazyk-bot.git
cd rusyazyk-bot

2. Создать виртуальное окружение

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux / Mac
python3 -m venv .venv
source .venv/bin/activate

3. Установить зависимости

pip install python-telegram-bot requests urllib3 selenium webdriver-manager

4. Получить токены

Telegram токен:

1. Открой @BotFather в Telegram
2. Напиши /newbot
3. Следуй инструкциям — получишь токен вида 1234567890:ABCdef...

Groq API ключ:

1. Зайди на console.groq.com
2. Зарегистрируйся (бесплатно)
3. Создай API ключ в разделе API Keys

5. Вставить токены в bot.py

Открой bot.py и в самом начале замени:

TELEGRAM_TOKEN = "СЮДА_ВСТАВЬ_ТОКЕН_ОТ_BOTFATHER"
GROQ_API_KEY   = "вставь_сюда"

6. Запустить бота

python bot.py

Бот запустится и будет работать пока открыт терминал.
Для остановки: Ctrl+C

---

📚 Сборка базы знаний (опционально, но рекомендуется)

База знаний значительно улучшает качество ответов — бот будет находить точные правила из 50+ сайтов.

Установить Selenium (для JS-сайтов)

pip install selenium webdriver-manager

Chrome должен быть установлен на компьютере.
ChromeDriver скачается автоматически.

Запустить краулер

python crawler.py

Краулер будет работать в фоне и собирать страницы.
Можно остановить в любой момент — при следующем запуске продолжит с того места.

Полезные команды:

python crawler.py --stats              # сколько страниц в базе
python crawler.py --search нн суффикс  # тест поиска по базе

Примерное время сбора:

Страниц	Время	Размер
10 000	~1 час	~50 МБ
50 000	~6 часов	~250 МБ
500 000	~3 дня	~2.5 ГБ

---

⚙️ Настройки в bot.py

TELEGRAM_TOKEN = "..."      # токен бота
GROQ_API_KEY   = "..."      # ключ Groq API
GROQ_MODEL     = "llama-3.3-70b-versatile"  # модель

Лимиты Groq API (бесплатный план):

• 14 400 запросов / день
• 30 запросов / минуту

---

🔧 Настройки краулера (crawler.py)

MAX_WORKERS  = 24       # потоков (рекомендуется = кол-во ядер × 2)
SELENIUM_W   = 4        # потоков Selenium (1 поток ≈ 300 МБ RAM)
MAX_PAGES    = 500_000  # цель (при 400 ГБ можно ставить 5_000_000)
DELAY        = 0.3      # пауза между запросами к одному сайту

---

📊 Команды бота

Команда	Описание
/start	Главное меню
/help	Справка
/stats	Статистика (запросы, кэш, топ функций)
/db	Статистика базы знаний

---

🏗️ Архитектура RAG

Запрос пользователя
       ↓
1. 🗄️  rusdb.db (локальная база)     ← мгновенно
       ↓
2. 📚  rules.json (1659 правил)       ← мгновенно  
       ↓
3. 🌐  Интернет (gramota.ru и др.)    ← 1-3 сек
       ↓
4. 🤖  Llama 3.3 70B (Groq)          ← 2-5 сек
       ↓
5. ✅  Валидация ответа
       ↓
6. 💾  Сохранение в кэш (30 дней)

---

🛡️ Безопасность

• Rate limiting: максимум 20 запросов в минуту на пользователя
• Кэш: SQLite, 30 дней, до 10 000 записей
• Токены: храни в .env файле, не заливай на GitHub!

Добавь в .gitignore:

.env
stats.json
cache.db
rusdb.db
*.pyc
__pycache__/
.venv/

---

📝 Лицензия

MIT — используй свободно, упомяни авторов.

---

🙏 Благодарности

• Groq — бесплатный API
• gramota.ru — главный источник правил
• python-telegram-bot — библиотека