AI Chat Helper Bot

🤖 Telegram-бот для анализа и поиска в рабочих чатах.
Находится в активной разработке.

---

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

├── allowed_users.csv # Список ID пользователей с правом добавлять бота

├── config.py # Настройки: токен, пути, глобальные параметры

├── main.py # Точка входа. Запуск бота и подключение компонентов

├── requirements.txt # Зависимости (aiogram, python-dotenv и др.)

├── bot_logic/ # Бизнес-логика бота (обработка сообщений, поиск)

├── databases/ # Работа с хранилищем (пока CSV, потом — БД)

├── handlers/ # Обработчики событий: команды, сообщения, callback

├── keyboards/ # Генерация inline и reply-клавиатур

├── middlewares/ # Промежуточная логика (проверка чатов, доступа)

├── services/ # Внешние сервисы: GPT, распознавание речи и др.

└── utilits/ # Вспомогательные утилиты (работа с файлами, датами)

---

⚙️ Текущий статус проработки

• Бот может добавляться в чаты только авторизованными пользователями (список в
  allowed_users.csv
  ).
• Реагирует на события добавления (
  my_chat_member
  ).
• Активирует чат, если он добавлен доверённым пользователем.
• В чате помечает сообщения заданного типа эмодзи - для демонстрации того что обработка происходит.
• Переадресация сообщений заданного типа в указанный топик.

---

⚙ Конфигурация (из

config.py

)

---

🔐 Переменные окружения (

.env

)

Бот использует переменные окружения :

• токен бота
• временный пароль для тестовой регистрации
• API ключи LLM провайдеров

---

🔧 Основные функции

1. Обработка текстовых и голосовых сообщений
2. Распознавание речи (из голосовых сообщений в текст, ограничение по умолчанию 2 МБ)
3. Формирование контекста со временем, пользователем и вложениями
4. История сообщений (поддерживается до N последних)
5. Извлечение структурированных данных из ответа LLM
6. Сохранение событий в базу данных
7. Просмотр событий в базе

---

📥 Поддерживаемые типы сообщений

• ✅ Текст — обычные текстовые сообщения
• ✅ Голосовые сообщения — автоматически распознаются в текст
• ✅ Фото — добавляются в контекст как вложения (
  photo_<id>.jpg
  )
• ✅ Документы — имена файлов сохраняются (
  document_<id>.doc
  или оригинальное имя)

---

🔄 Как работает обработка

1. Пришло сообщение → проверяется тип

   • Если голосовое → скачивается и распознаётся в текст
   • Если текстовое → обрабатывается напрямую

2. Формируется контекст:

3. Контекст и история отправляются в LLM с системным промптом и схемой

4. LLM возвращает JSON вида: { "type": "event_type", ... "key": "value" }

5. Проверка типа операции:

   • Если
     type
     в списке разрешённых (
     VALID_OPERATION_TYPES
     ) → сохраняется в БД
   • Если
     type == "pass"
     → сообщение игнорируется
   • Иначе → ошибка

6. Сообщение добавляется в историю (макс.

   history_len
   сообщений)

---

🗃️ Сохранение в базу данных

Каждое валидное событие сохраняется в таком виде:

---

🤖 Системный промпт и LLM

• Можно использовать любые LLM через
  LLMConstructorLangChain
• Системный промпт задаётся в
  services/gpt/gpt_promts.py
• Ожидается, что LLM возвращает валидный JSON
• Ответ парсится, проверяется и используется для классификации

🔧 Для тестирования

• создать новую группу и добавить туда @ai_chats_manager_bot
• написать в созданной группе с ботом любое сообщение. Реакции на него не должно быть
• перейти в личку с ботом, выбрать команду /start . Бот должен ответить что у вас нет прав и рекомендовать регистрацию
• для регистрации ввести /register <пароль> . Если пароль верный - будет сообщение об успешной регистрации
• создать новую группу с ботом (либо удалить из группы, созданной на шаге 1 и добавить заново)
• если всё сделано правильно - теперь бот будет отвечать на любое сообщение в чате. Не только от создателя