Metadata-Version: 2.4
Name: ekogram
Version: 3.1
Summary: Lightweight library for working with Telegram Bot Api + Generate Images, Audio and Text
Home-page: https://github.com/SiriRSST/Ekogram
Author: Siri-Team
Author-email: siriteamrs@gmail.com
License: MIT
Project-URL: Source, https://github.com/SiriRSST/Ekogram
Keywords: telebot,bot,gram,pytelegrambotapi,telegram,ekogram,aiogram,gpt,freegpt,openai,ai
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: bs4
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Ekogram

**Ekogram** — лёгкий Python-модуль для Telegram Bot API и работы с нейросетями.  
Он объединяет простую работу с Telegram и мощные функции: генерация текста и изображений, перевод и озвучка.

## Установка

```bash
pip install ekogram
```

или для macOS:

```bash
pip3 install ekogram
```

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

- Telegram Bot API: отправка сообщений, медиа, inline, reply клавиатуры и т.п.
- Мощные AI-инструменты: ИИ, генерация картинок, перевод, озвучка.
- Поддержка классов Telegram: `Message`, `User`, `Chat`, `Audio`, `Photo`, `Voice` и т.д.
- Работа с `callback_query`, `inline_query`, `handlers`

---

## 🤖 Быстрый старт бота

```python
from ekogram import Bot

bot = Bot("ВАШ_ТОКЕН")

@bot.message_handler(commands=["start"])
def start_handler(message):
    bot.reply_message(chat_id=message.chat.id, text="Привет! Я бот Ekogram!")

bot.polling()
```

---

## 🧠 Использование AI

### `OnlySQ` — бесплатный набор ИИ; `Deef` — дополнительные функции

```python
from ekogram import OnlySQ

gpt = OnlySQ()

messages = [
    {"role": "system", "content": "Отвечай кратко и по делу"},
    {"role": "user", "content": "Расскажи, кто такой Эйнштейн?"}
]

print(gpt.generate_answer("gpt-5.2-chat", messages))
```

### `OnlySQ` — генерация картинок

```python
from ekogram import OnlySQ

img = OnlySQ()
print(img.generate_image(prompt="cyberpunk robot with fire"))
```

### `Deef` — перевод текста

```python
from ekogram import Deef

tr = Deef()
print(tr.translate("Hello, how are you?", lang="ru"))
```

### `ChatGPT` — сессия с GPT

```python
from ekogram import ChatGPT

chat = ChatGPT(url='-', headers={})
print(chat.generate_chat_completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}]))
```

---

## 🎤 Озвучка текста

```python
from ekogram import Deef

gpt = Deef()
gpt.speech(text="Привет, как дела?", path="voice.mp3", voice="nova")
```

---

## 📎 Пример кнопок

```python
from ekogram import Bot, Markup

bot = Bot("TOKEN")

@bot.message_handler(commands=["menu"])
def menu(message):
    buttons = [{"text": "Кнопка 1"}, {"text": "Кнопка 2"}]
    markup = Markup.create_reply_keyboard(buttons)
    bot.reply_message(chat_id=message.chat.id, text="Выберите вариант:", reply_markup=markup)
```

---

## 📌 Поддерживаемые классы

### Telegram: Модели данных

- `User` — пользователь Telegram
- `Chat` — чат (личный, группа, супергруппа)
- `Message` — сообщение
- `File` — файл
- `Photo`, `PhotoSize` — фотографии
- `Voice` — голосовые сообщения
- `Video`, `VideoNote` — видео и видеозаметки
- `Audio` — аудиофайлы
- `Sticker` — стикеры
- `Animation` — анимации (GIF)
- `Document` — документы
- `Location` — геолокация
- `Venue` — места проведения
- `Contact` — контакты
- `Dice` — броски игральных костей

### Telegram: Участники и права

- `ChatMember` — участник чата
- `ChatPermissions` — права участников

### Telegram: Медиа

- `InputMediaPhoto`, `InputMediaVideo`, `InputMediaAnimation`, `InputMediaAudio`, `InputMediaDocument` — отправка медиа

### Telegram: Inline

- `InlineQuery`, `InlineQueryResultArticle`, `InlineQueryResultPhoto`, `InlineQueryResultVideo`

### Telegram: Markup

- `Markup.create_inline_keyboard()`, `Markup.create_reply_keyboard()`, `Markup.remove_reply_keyboard()`

### AI

- `OnlySQ`, `Deef`, `ChatGPT`

---

## 📚 Справочник классов

### Классы моделей Telegram

#### User

Класс для представления пользователя Telegram.

**Атрибуты:**

- `id` (int) — уникальный идентификатор пользователя
- `is_bot` (bool) — является ли пользователь ботом
- `first_name` (str) — имя пользователя
- `last_name` (str) — фамилия пользователя (опционально)
- `username` (str) — юзернейм пользователя (опционально)
- `language_code` (str) — код языка пользователя (опционально)
- `is_premium` (bool) — имеет ли пользователь Premium (опционально)
- `added_to_attachment_menu` (bool) — добавлен ли бот в меню вложений (опционально)
- `can_join_groups` (bool) — может ли бот присоединяться к группам (опционально)
- `can_read_all_group_messages` (bool) — может ли бот читать все сообщения группы (опционально)
- `supports_inline_queries` (bool) — поддерживает ли пользователь inline-запросы (опционально)
- `can_connect_to_business` (bool) — может ли подключаться к бизнесу (опционально)
- `has_main_web_app` (bool) — имеет ли главное веб-приложение (опционально)
- `has_topics_enabled` (bool) — включены ли темы (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект User из словаря данных
- `__repr__()` — строковое представление объекта

---

#### Chat

Класс для представления чата.

**Атрибуты:**

- `id` (Union[int, str]) — уникальный идентификатор чата
- `type` (str) — тип чата: "private", "group", "supergroup", "channel"
- `title` (str) — название чата (для групп и каналов)
- `username` (str) — юзернейм чата (опционально)
- `first_name` (str) — имя собеседника (для личных чатов)
- `last_name` (str) — фамилия собеседника (опционально)
- `is_forum` (bool) — является ли чат форумом (опционально)
- `photo` (dict) — фото чата (опционально)
- `active_usernames` (List[str]) — активные юзернеймы (опционально)
- `bio` (str) — описание профиля (опционально)
- `description` (str) — описание группы (опционально)
- `invite_link` (str) — ссылка-приглашение (опционально)
- `permissions` (dict) — права по умолчанию (опционально)
- `slow_mode_delay` (int) — задержка slow mode (опционально)
- `has_protected_content` (bool) — защищён ли контент (опционально)
- `sticker_set_name` (str) — название набора стикеров (опционально)
- `can_set_sticker_set` (bool) — можно ли установить набор стикеров (опционально)
- `linked_chat_id` (int) — связанный чат (опционально)
- `location` (dict) — локация (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект Chat из словаря данных
- `__repr__()` — строковое представление объекта

---

#### ChatMember

Класс для представления участника чата.

**Атрибуты:**

- `user` (User) — информация о пользователе
- `status` (str) — статус участника: "creator", "administrator", "member", "restricted", "left", "kicked"
- `is_anonymous` (bool) — является ли анонимным (опционально)
- `custom_title` (str) — кастомный титул (опционально)
- `can_be_edited` (bool) — можно ли редактировать (опционально, для админов)
- `can_manage_chat` (bool) — управление чатом (опционально)
- `can_delete_messages` (bool) — удаление сообщений (опционально)
- `can_manage_video_chats` (bool) — управление видеочатами (опционально)
- `can_manage_topics` (bool) — управление темами (опционально)
- `can_restrict_members` (bool) — ограничение участников (опционально)
- `can_promote_members` (bool) — повышение участников (опционально)
- `can_change_info` (bool) — изменение информации (опционально)
- `can_invite_users` (bool) — приглашение пользователей (опционально)
- `can_pin_messages` (bool) — закрепление сообщений (опционально)
- `is_member` (bool) — является ли участником (опционально, для restricted)
- `until_date` (int) — дата окончания ограничения (опционально)
- `can_send_messages` (bool) — отправка сообщений (опционально)
- `can_send_media_messages` (bool) — отправка медиа (опционально)
- `can_send_polls` (bool) — отправка опросов (опционально)
- `can_send_other_messages` (bool) — отправка других сообщений (опционально)
- `can_add_web_page_previews` (bool) — превью ссылок (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект ChatMember из словаря данных
- `__repr__()` — строковое представление объекта

---

#### ChatPermissions

Класс для управления правами участников чата.

**Атрибуты:**

- `can_send_messages` (bool) — отправка сообщений
- `can_send_media_messages` (bool) — отправка медиа
- `can_send_polls` (bool) — отправка опросов
- `can_send_other_messages` (bool) — отправка других сообщений
- `can_add_web_page_previews` (bool) — превью веб-страниц
- `can_change_info` (bool) — изменение информации чата
- `can_invite_users` (bool) — приглашение пользователей
- `can_pin_messages` (bool) — закрепление сообщений
- `can_manage_topics` (bool) — управление темами
- `can_send_audios` (bool) — отправка аудио
- `can_send_documents` (bool) — отправка документов
- `can_send_photos` (bool) — отправка фото
- `can_send_videos` (bool) — отправка видео
- `can_send_video_notes` (bool) — отправка видеозаметок
- `can_send_voice_notes` (bool) — отправка голосовых
- `can_use_stories` (bool) — использование историй
- `can_post_stories` (bool) — публикация историй
- `can_edit_stories` (bool) — редактирование историй
- `can_delete_stories` (bool) — удаление историй
- `can_manage_anti_spam` (bool) — управление антиспамом

**Методы:**

- `to_dict()` — преобразует объект в словарь
- `from_dict(data: dict)` — создаёт объект из словаря
- `__repr__()` — строковое представление объекта

---

#### PhotoSize

Класс для представления размера фотографии.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `width` (int) — ширина фото
- `height` (int) — высота фото
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Photo

Класс для представления фотографии.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `width` (int) — ширина фото
- `height` (int) — высота фото
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Audio

Класс для представления аудиофайла.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `duration` (int) — длительность в секундах
- `performer` (str) — исполнитель (опционально)
- `title` (str) — название трека (опционально)
- `file_name` (str) — имя файла (опционально)
- `mime_type` (str) — MIME-тип файла (опционально)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Voice

Класс для представления голосового сообщения.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `duration` (int) — длительность в секундах
- `mime_type` (str) — MIME-тип файла (опционально)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Video

Класс для представления видеофайла.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `duration` (int) — длительность в секундах
- `width` (int) — ширина видео
- `height` (int) — высота видео
- `file_name` (str) — имя файла (опционально)
- `mime_type` (str) — MIME-тип файла (опционально)
- `file_size` (int) — размер файла (опционально)
- `supports_streaming` (bool) — поддерживает ли стриминг (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### VideoNote

Класс для представления видеозаметки.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `duration` (int) — длительность в секундах
- `length` (int) — длина (ширина и высота равны)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Animation

Класс для представления анимации (GIF).

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `width` (int) — ширина анимации
- `height` (int) — высота анимации
- `duration` (int) — длительность в секундах
- `file_name` (str) — имя файла (опционально)
- `mime_type` (str) — MIME-тип файла (опционально)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Dice

Класс для представления броска игральной кости.

**Атрибуты:**

- `emoji` (str) — эмодзи игральной кости
- `value` (int) — выпавшее значение
- `animation_duration` (int) — длительность анимации (опционально)
- `static_url` (str) — URL статического изображения (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Sticker

Класс для представления стикера.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `width` (int) — ширина стикера
- `height` (int) — высота стикера
- `is_animated` (bool) — является ли анимированным
- `is_video` (bool) — является ли видеостикером
- `emoji` (str) — связанный эмодзи (опционально)
- `set_name` (str) — название набора стикеров (опционально)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)
- `mask_position` (dict) — позиция маски (опционально)
- `premium_animation` (dict) — Premium-анимация (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Location

Класс для представления геолокации.

**Атрибуты:**

- `latitude` (float) — широта
- `longitude` (float) — долгота
- `horizontal_accuracy` (float) — точность в метрах (опционально)
- `live_period` (int) — период живой локации (опционально)
- `heading` (int) — направление движения (опционально)
- `proximity_alert_radius` (int) — радиус уведомления (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря
- `to_dict()` — преобразует объект в словарь

---

#### Venue

Класс для представления места проведения.

**Атрибуты:**

- `location` (Location) — локация
- `title` (str) — название места
- `address` (str) — адрес
- `foursquare_id` (str) — ID Foursquare (опционально)
- `foursquare_type` (str) — тип Foursquare (опционально)
- `google_place_id` (str) — ID Google Places (опционально)
- `google_place_type` (str) — тип Google Places (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Contact

Класс для представления контактных данных.

**Атрибуты:**

- `phone_number` (str) — номер телефона
- `first_name` (str) — имя
- `last_name` (str) — фамилия (опционально)
- `user_id` (int) — ID пользователя в Telegram (опционально)
- `vcard` (str) — визитная карточка (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### Document

Класс для представления документа.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `file_name` (str) — имя файла (опционально)
- `mime_type` (str) — MIME-тип файла (опционально)
- `file_size` (int) — размер файла (опционально)
- `thumbnail` (PhotoSize) — миниатюра (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### File

Класс для представления файла.

**Атрибуты:**

- `file_id` (str) — уникальный идентификатор файла
- `file_unique_id` (str) — уникальный идентификатор файла
- `file_size` (int) — размер файла (опционально)
- `file_path` (str) — путь к файлу (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### WebhookInfo

Класс для представления информации о вебхуке.

**Атрибуты:**

- `url` (str) — URL вебхука (опционально)
- `has_custom_certificate` (bool) — есть ли кастомный сертификат (опционально)
- `pending_update_count` (int) — количество ожидающих обновлений (опционально)
- `last_error_date` (int) — дата последней ошибки (опционально)
- `last_error_message` (str) — сообщение последней ошибки (опционально)
- `last_synchronization_error_date` (int) — дата ошибки синхронизации (опционально)
- `max_connections` (int) — максимальное количество соединений (опционально)
- `allowed_updates` (list) — разрешённые обновления (опционально)
- `ip_address` (str) — IP-адрес (опционально)
- `protect_content` (bool) — защита контента (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### InputFile

Класс для представления файла, отправляемого через Bot API.

**Атрибуты:**

- `file_path` (str) — путь к файлу

**Методы:**

- `__str__()` — возвращает file_path

---

#### CallbackQuery

Класс для обработки callback-запросов.

**Атрибуты:**

- `id` (str) — уникальный идентификатор callback-запроса
- `from_user` (User) — пользователь, отправивший запрос
- `data` (str) — данные callback (опционально)
- `message` (Message) — связанное сообщение (опционально)
- `inline_message_id` (str) — ID inline-сообщения (опционально)
- `chat_instance` (str) — экземпляр чата (опционально)
- `game_short_name` (str) — короткое название игры (опционально)

---

#### ForumTopic

Класс для представления темы форума.

**Атрибуты:**

- `message_thread_id` (int) — ID темы
- `name` (str) — название темы
- `icon_color` (int) — цвет иконки
- `icon_custom_emoji_id` (str) — кастомный эмодзи иконки (опционально)
- `is_name_implicit` (bool) — неявное название (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### MessageEntity

Класс для описания форматирования текста.

**Атрибуты:**

- `type` (str) — тип сущности (mention, hashtag, bot_command, url, email, phone_number, bold, italic, underline, strikethrough, code, pre, text_link, text_mention)
- `offset` (int) — смещение в тексте
- `length` (int) — длина сущности
- `url` (str) — URL (опционально)
- `user` (User) — пользователь (опционально)
- `language` (str) — язык (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### Message

Класс для представления сообщения.

**Атрибуты:**

- `message_id` (int) — уникальный ID сообщения
- `chat` (Chat) — чат, в котором отправлено сообщение
- `from_user` (User) — отправитель (опционально)
- `text` (str) — текст сообщения (опционально)
- `date` (int) — дата отправки в Unix time
- `message_thread_id` (int) — ID темы (опционально)
- `is_topic_message` (bool) — является ли сообщение темой (опционально)
- `reply_to_message` (Message) — сообщение в ответе (опционально)
- `content_type` (str) — тип контента (опционально)
- `photo` (list) — фото (опционально)
- `audio` (Audio) — аудио (опционально)
- `video` (Video) — видео (опционально)
- `video_note` (VideoNote) — видеозаметка (опционально)
- `voice` (Voice) — голосовое (опционально)
- `animation` (Animation) — анимация (опционально)
- `dice` (Dice) — игральная кость (опционально)
- `sticker` (Sticker) — стикер (опционально)
- `document` (Document) — документ (опционально)
- `caption` (str) — подпись к медиа (опционально)
- `new_chat_members` (list) — новые участники (опционально)
- `left_chat_member` (User) — вышедший участник (опционально)
- `entities` (list) — сущности текста (опционально)
- `venue` (Venue) — место (опционально)
- `contact` (Contact) — контакт (опционально)
- `location` (Location) — локация (опционально)
- `poll` (dict) — опрос (опционально)
- `forward_from` (User) — пересланный от (опционально)
- `forward_date` (int) — дата пересылки (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект Message из словаря данных

---

#### UserProfilePhotos

Класс для фотографий профиля пользователя.

**Атрибуты:**

- `total_count` (int) — общее количество фото
- `photos` (list) — список фото (каждый элемент — список PhotoSize)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### LabeledPrice

Класс для обработки платежей.

**Атрибуты:**

- `label` (str) — метка цены
- `amount` (int) — сумма в копейках

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### ShippingOption

Класс для вариантов доставки.

**Атрибуты:**

- `id` (str) — уникальный ID варианта
- `title` (str) — название варианта
- `prices` (list) — список цен (LabeledPrice)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InlineQuery

Класс для обработки inline-запросов.

**Атрибуты:**

- `id` (str) — уникальный ID запроса
- `from_user` (User) — пользователь
- `query` (str) — текст запроса
- `offset` (str) — смещение для пагинации
- `chat_type` (str) — тип чата (опционально)
- `location` (Location) — локация (опционально)

**Методы:**

- `from_dict(data: dict)` — создаёт объект из словаря

---

#### InlineQueryResult (базовый)

Базовый класс для inline-результатов.

**Атрибуты:**

- `type` (str) — тип результата
- `id` (str) — уникальный ID результата

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InlineQueryResultArticle

Класс для отправки статьи.

**Атрибуты:**

- `id` (str) — уникальный ID
- `title` (str) — заголовок статьи
- `input_message_content` (dict) — содержание сообщения
- `reply_markup` (dict) — клавиатура (опционально)
- `url` (str) — URL (опционально)
- `hide_url` (bool) — скрыть URL (опционально)
- `description` (str) — описание (опционально)
- `thumb_url` (str) — URL миниатюры (опционально)
- `thumb_width` (int) — ширина миниатюры (опционально)
- `thumb_height` (int) — высота миниатюры (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InlineQueryResultPhoto

Класс для отправки фото.

**Атрибуты:**

- `id` (str) — уникальный ID
- `photo_url` (str) — URL фото
- `thumb_url` (str) — URL миниатюры
- `photo_width` (int) — ширина фото (опционально)
- `photo_height` (int) — высота фото (опционально)
- `title` (str) — заголовок (опционально)
- `description` (str) — описание (опционально)
- `caption` (str) — подпись (опционально)
- `parse_mode` (str) — режим форматирования (опционально)
- `reply_markup` (dict) — клавиатура (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InlineQueryResultVideo

Класс для отправки видео.

**Атрибуты:**

- `id` (str) — уникальный ID
- `video_url` (str) — URL видео
- `mime_type` (str) — MIME-тип
- `thumb_url` (str) — URL миниатюры
- `title` (str) — заголовок
- `caption` (str) — подпись (опционально)
- `parse_mode` (str) — режим форматирования (опционально)
- `video_width` (int) — ширина видео (опционально)
- `video_height` (int) — высота видео (опционально)
- `video_duration` (int) — длительность видео (опционально)
- `description` (str) — описание (опционально)
- `reply_markup` (dict) — клавиатура (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMedia (базовый)

Базовый класс для медиа контента.

**Атрибуты:**

- `media` (str) — медиа (file_id, URL или путь к файлу)
- `caption` (str) — подпись (опционально)
- `parse_mode` (str) — режим форматирования (опционально)
- `caption_entities` (list) — сущности подписи (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMediaPhoto

Класс для отправки фото. Наследуется от InputMedia.

**Дополнительные атрибуты:**

- `type` (str) — тип медиа ('photo')
- `show_caption_above_media` (bool) — показать подпись над медиа (опционально)
- `has_spoiler` (bool) — содержит спойлер (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMediaVideo

Класс для отправки видео. Наследуется от InputMedia.

**Дополнительные атрибуты:**

- `type` (str) — тип медиа ('video')
- `show_caption_above_media` (bool) — показать подпись над медиа (опционально)
- `width` (int) — ширина видео (опционально)
- `height` (int) — высота видео (опционально)
- `duration` (int) — длительность (опционально)
- `supports_streaming` (bool) — поддержка стриминга (опционально)
- `has_spoiler` (bool) — содержит спойлер (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMediaAnimation

Класс для отправки анимации. Наследуется от InputMedia.

**Дополнительные атрибуты:**

- `type` (str) — тип медиа ('animation')
- `width` (int) — ширина анимации (опционально)
- `height` (int) — высота анимации (опционально)
- `duration` (int) — длительность (опционально)
- `show_caption_above_media` (bool) — показать подпись над медиа (опционально)
- `has_spoiler` (bool) — содержит спойлер (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMediaAudio

Класс для отправки аудиофайлов. Наследуется от InputMedia.

**Дополнительные атрибуты:**

- `type` (str) — тип медиа ('audio')
- `duration` (int) — длительность (опционально)
- `performer` (str) — исполнитель (опционально)
- `title` (str) — название (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

#### InputMediaDocument

Класс для отправки документов. Наследуется от InputMedia.

**Дополнительные атрибуты:**

- `type` (str) — тип медиа ('document')
- `disable_content_type_detection` (bool) — отключить определение типа контента (опционально)

**Методы:**

- `to_dict()` — преобразует объект в словарь

---

### Markup

Класс для создания клавиатур.

**Методы:**

- `create_reply_keyboard(buttons: list, resize: bool = True, one_time: bool = False, selective: bool = False)` — создаёт reply-клавиатуру
  - `buttons` — список кнопок (список словарей с ключом "text")
  - `resize` — изменять размер клавиатуры
  - `one_time` — скрывать после использования
  - `selective` — показывать только выбранным пользователям

- `create_inline_keyboard(inline_keyboard: list, resize: bool = True, one_time: bool = False)` — создаёт inline-клавиатуру
  - `inline_keyboard` — двумерный список кнопок
  - Каждая кнопка содержит "text" и "callback_data" или "url"

- `remove_reply_keyboard(selective: bool = False)` — удаляет reply-клавиатуру
  - `selective` — выборочное удаление

---

### Bot

Основной класс для работы с Telegram Bot API.

**Конструктор:**

- `__init__(token: str, bot_username: str = None)` — создаёт экземпляр бота
  - `token` — токен бота от @BotFather
  - `bot_username` — юзернейм бота (опционально, определяется автоматически)

**Методы отправки сообщений:**

- `send_message(chat_id: Union[int, str], text: str, mode: str = "Markdown", disable_web_page_preview: bool = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, entities: list = None, link_preview_options: dict = None, disable_notification: bool = None) -> Message` — отправляет сообщение

- `reply_message(chat_id: Union[int, str], text: str, mode: str = "Markdown", message_id: int = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, entities: list = None, disable_notification: bool = None) -> Message` — отправляет сообщение в ответ

- `reply_text(chat_id: Union[int, str], text: str, mode: str = "Markdown", message_id: int = None, reply_markup: Union[dict, Markup] = None, entities: list = None, disable_notification: bool = None) -> Message` — отправляет текстовое сообщение

- `forward_message(chat_id: Union[int, str], from_chat_id: Union[int, str], message_id: int, disable_notification: bool = None, message_thread_id: int = None) -> Message` — пересылает сообщение

**Методы отправки медиа:**

- `send_photo(chat_id: Union[int, str], photo: Union[str, bytes, InputFile], caption: str = None, mode: str = "Markdown", reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, has_spoiler: bool = None, disable_notification: bool = None) -> Message` — отправляет фото

- `send_audio(chat_id: Union[int, str], audio: Union[str, bytes, InputFile], caption: str = None, duration: int = None, performer: str = None, title: str = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет аудио

- `send_voice(chat_id: Union[int, str], voice: Union[str, bytes, InputFile], caption: str = None, duration: int = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет голосовое сообщение

- `send_video(chat_id: Union[int, str], video: Union[str, bytes, InputFile], caption: str = None, duration: int = None, width: int = None, height: int = None, supports_streaming: bool = False, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, has_spoiler: bool = None, disable_notification: bool = None) -> Message` — отправляет видео

- `send_video_note(chat_id: Union[int, str], video_note: Union[str, bytes, InputFile], duration: int = None, length: int = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет видеозаметку

- `send_animation(chat_id: Union[int, str], animation: Union[str, bytes, InputFile], duration: int = None, width: int = None, height: int = None, caption: str = None, mode: str = "Markdown", reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, has_spoiler: bool = None, disable_notification: bool = None) -> Message` — отправляет анимацию (GIF)

- `send_sticker(chat_id: Union[int, str], sticker: Union[str, bytes, InputFile], emoji: str = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет стикер

- `send_document(chat_id: Union[int, str], document: Union[str, bytes, InputFile], caption: str = None, mode: str = "Markdown", reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет документ

- `send_dice(chat_id: Union[int, str], emoji: str = "🎲", reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет игральную кость

- `send_location(chat_id: Union[int, str], latitude: float, longitude: float, horizontal_accuracy: float = None, live_period: int = None, heading: int = None, proximity_alert_radius: int = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет локацию

- `send_venue(chat_id: Union[int, str], latitude: float, longitude: float, title: str, address: str, foursquare_id: str = None, foursquare_type: str = None, google_place_id: str = None, google_place_type: str = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет место

- `send_contact(chat_id: Union[int, str], phone_number: str, first_name: str, last_name: str = None, vcard: str = None, reply_markup: Union[dict, Markup] = None, protect_content: bool = None, message_thread_id: int = None, disable_notification: bool = None) -> Message` — отправляет контакт

**Методы редактирования:**

- `edit_message_text(chat_id: Union[int, str] = None, message_id: int = None, text: str = None, inline_message_id: str = None, mode: str = "Markdown", reply_markup: Union[dict, Markup] = None, link_preview_options: dict = None) -> bool` — редактирует текст сообщения

- `edit_message_caption(chat_id: Union[int, str] = None, message_id: int = None, caption: str = None, inline_message_id: str = None, mode: str = "Markdown", show_caption_above_media: bool = False, reply_markup: Union[dict, Markup] = None, caption_entities: list = None) -> bool` — редактирует подпись к медиа

- `edit_message_reply_markup(chat_id: Union[int, str] = None, message_id: int = None, reply_markup: Union[dict, Markup] = None, inline_message_id: str = None) -> bool` — редактирует клавиатуру сообщения

- `edit_message_live_location(chat_id: Union[int, str] = None, message_id: int = None, inline_message_id: str = None, latitude: float = None, longitude: float = None, horizontal_accuracy: float = None, heading: int = None, proximity_alert_radius: int = None, reply_markup: Union[dict, Markup] = None, live_period: int = None) -> Message` — редактирует живую локацию

- `stop_message_live_location(chat_id: Union[int, str] = None, message_id: int = None, inline_message_id: str = None, reply_markup: Union[dict, Markup] = None) -> Message` — останавливает обновление живой локации

**Методы удаления:**

- `delete_message(chat_id: Union[int, str] = None, message_id: int = None) -> bool` — удаляет сообщение

**Методы получения информации:**

- `get_me() -> Optional[User]` — получает информацию о боте

- `get_user_profile_photos(user_id: int = None, limit: int = 100, offset: int = None) -> Optional[UserProfilePhotos]` — получает фото профиля пользователя

- `get_file(file_id: str = None) -> Optional[File]` — получает информацию о файле

- `get_chat(chat_id: Union[int, str] = None) -> Optional[Chat]` — получает информацию о чате

- `get_chat_administrators(chat_id: Union[int, str] = None) -> list` — получает администраторов чата

- `get_chat_members_count(chat_id: Union[int, str] = None) -> int` — получает количество участников чата

- `get_chat_member(chat_id: Union[int, str] = None, user_id: int = None) -> Optional[ChatMember]` — получает информацию об участнике чата

- `get_webhook_info(timeout: int = 30, drop_pending_updates: bool = None) -> Optional[WebhookInfo]` — получает информацию о вебхуке

**Методы управления чатом:**

- `set_webhook(url: str = None, certificate: str = None, max_connections: int = None, allowed_updates: Union[list, str] = None, ip_address: str = None, drop_pending_updates: bool = None, secret_token: str = None) -> Optional[WebhookInfo]` — устанавливает вебхук

- `delete_webhook(drop_pending_updates: bool = False) -> bool` — удаляет вебхук

- `set_chat_photo(chat_id: Union[int, str] = None, photo: Union[str, bytes, InputFile] = None) -> bool` — устанавливает фото чата

- `delete_chat_photo(chat_id: Union[int, str] = None) -> bool` — удаляет фото чата

- `set_chat_title(chat_id: Union[int, str] = None, title: str = None) -> bool` — устанавливает название чата

- `set_chat_description(chat_id: Union[int, str] = None, description: str = None) -> bool` — устанавливает описание чата

- `leave_chat(chat_id: Union[int, str] = None) -> bool` — покидает чат

**Методы управления участниками:**

- `kick_chat_member(chat_id: Union[int, str] = None, user_id: int = None, until_date: float = None) -> bool` — исключает пользователя из чата

- `ban_chat_member(chat_id: Union[int, str] = None, user_id: int = None, until_date: float = None, revoke_messages: bool = False) -> bool` — блокирует пользователя в чате

- `unban_chat_member(chat_id: Union[int, str] = None, user_id: int = None, only_if_banned: bool = False) -> bool` — разблокирует пользователя

- `mute_user(chat_id: Union[int, str] = None, user_id: int = None, duration: int = 3600, use_independent_chat_permissions: bool = None) -> bool` — запрещает пользователю отправлять сообщения

- `unmute_user(chat_id: Union[int, str] = None, user_id: int = None, use_independent_chat_permissions: bool = None) -> bool` — разрешает пользователю отправлять сообщения

- `restrict_chat_member(chat_id: Union[int, str] = None, user_id: int = None, permissions: ChatPermissions = None, until_date: float = None, use_independent_chat_permissions: bool = None) -> bool` — изменяет права пользователя

- `promote_chat_member(chat_id: Union[int, str] = None, user_id: int = None, can_change_info: bool = False, can_post_messages: bool = False, can_edit_messages: bool = False, can_delete_messages: bool = False, can_invite_users: bool = False, can_restrict_members: bool = False, can_pin_messages: bool = False, can_promote_members: bool = False, is_anonymous: bool = None, can_manage_chat: bool = None, can_manage_video_chats: bool = None, can_post_stories: bool = None, can_edit_stories: bool = None, can_delete_stories: bool = None) -> bool` — повышает права пользователя

- `set_chat_permissions(chat_id: Union[int, str] = None, permissions: ChatPermissions = None, use_independent_chat_permissions: bool = None) -> bool` — устанавливает права чата

**Методы получения обновлений:**

- `get_updates(timeout: int = 45, allowed_updates: Union[list, str] = None, long_polling_timeout: int = 45) -> list` — получает обновления

- `process_updates(updates: list = None)` — обрабатывает обновления

- `polling(interval: int = 1)` — запускает polling

- `always_polling(interval: int = 1, timeout: int = 45, long_polling_timeout: int = 45, allowed_updates: Union[list, str] = None, restart_on_error: bool = True)` — запускает бесконечный polling

- `stop_polling()` — останавливает polling

**Методы для работы с файлами:**

- `download_file(file: File = None, save_path: str = None, chunk_size: int = 1024, timeout: int = 60, headers: dict = None, stream: bool = True) -> bool` — скачивает файл с серверов Telegram

- `encode_base64(path: str = None) -> str` — кодирует файл в base64

**Методы для медиа-групп:**

- `reply_media_group(chat_id: Union[int, str] = None, media: list = None, disable_notification: bool = None, message_thread_id: int = None, protect_content: bool = None) -> Optional[list]` — отправляет группу медиа (до 10 объектов)

**Методы для работы с правами:**

- `chat_permissions(can_send_messages: bool = True, can_send_media_messages: bool = True, can_send_polls: bool = True, can_send_other_messages: bool = True, can_add_web_page_previews: bool = True, can_change_info: bool = False, can_invite_users: bool = True, can_pin_messages: bool = False) -> dict` — создаёт объект прав

**Декораторы для обработчиков:**

- `message_handler(func: callable = None, commands: list = None, regexp: str = None, content_types: list = None) -> callable` — декоратор для регистрации обработчика сообщений

- `callback_query_handler(func: callable = None, data: str = None) -> callable` — декоратор для callback-запросов

- `inline_query_handler(func: callable = None, query: str = None) -> callable` — декоратор для inline-запросов

**Методы для ответов на запросы:**

- `register_next_step_handler(message: Message = None, callback: callable = None, *args, **kwargs) -> None` — регистрирует следующий обработчик

- `answer_callback_query(callback_id: str = None, text: str = "Что-то забыли указать", show_alert: bool = False, url: str = None, cache_time: int = 0) -> bool` — отвечает на callback-запрос

- `answer_inline_query(inline_query_id: str = None, results: list = None, cache_time: int = None, is_personal: bool = None, next_offset: str = None, switch_pm_text: str = None, switch_pm_parameter: str = None, button: dict = None) -> bool` — отвечает на inline-запрос

**Вспомогательные методы:**

- `run_in_bg(func, *args, **kwargs)` — запускает функцию в фоне

---

### OnlySQ

Класс для работы с бесплатным API нейросетей OnlySQ.

**Методы:**

- `get_models(modality: str | list = None, can_tools: bool = None, can_stream: bool = None, status: str = None, max_cost: float = None, return_names: bool = False) -> list` — фильтрует модели по заданным параметрам
  - `modality` — модальность ('text', 'image', 'sound') или список модальностей
  - `can_tools` — фильтр по поддержке инструментов
  - `can_stream` — фильтр по возможности потоковой передачи
  - `status` — статус модели (например, 'work')
  - `max_cost` — максимальная стоимость (включительно)
  - `return_names` — если True, возвращает названия моделей вместо ключей
  - **Возвращает:** список отфильтрованных моделей (ключи или названия)

- `generate_answer(model: str = "gpt-5.2-chat", messages: dict = None) -> str` — генерация текста
  - `model` — модель для генерации (по умолчанию "gpt-5.2-chat")
  - `messages` — список сообщений в формате `[{"role": "...", "content": "..."}]`
  - **Возвращает:** сгенерированный текст или "Error" при ошибке

- `generate_image(model: str = "flux", prompt: str = None, ratio: str = "16:9", filename: str = 'image.png') -> bool` — генерация изображения
  - `model` — модель для генерации (по умолчанию "flux")
  - `prompt` — описание изображения
  - `ratio` — соотношение сторон (по умолчанию "16:9")
  - `filename` — имя файла для сохранения (по умолчанию "image.png")
  - **Возвращает:** True при успешном сохранении, False при ошибке

---

### Deef

Класс для дополнительных функций ИИ: перевод, сокращение ссылок, генерация текста, озвучка.

**Методы:**

- `translate(text: str = None, lang: str = "en") -> str` — перевод текста
  - `text` — текст для перевода
  - `lang` — целевой язык (по умолчанию "en")
  - **Возвращает:** переведённый текст

- `short_url(long_url: str = None) -> str` — сокращение ссылок
  - `long_url` — длинная ссылка
  - **Возвращает:** сокращённую ссылку

- `gen_ai_response(model: str = "Qwen3 235B", messages: list = None) -> dict[str]` — отправляет запрос к API и возвращает словарь с полной информацией
  - `model` — модель нейросети ("Qwen3 235B" или "GPT OSS 120B")
  - `messages` — список сообщений в формате `[{"role": "...", "content": "..."}]`
  - **Возвращает:** словарь с ключами:
    - `reasoning` — размышления модели
    - `answer` — финальный ответ модели
    - `status` — статус выполнения
    - `cluster_info` — информация о кластере (если есть)

- `gen_gpt(messages: list = None) -> str` — генерация текста с помощью GPT-4o (потоковая)
  - `messages` — список сообщений
  - **Возвращает:** текст ответа или "Error"

- `speech(text: str = None, voice: str = "nova", path: str = "ozv.mp3") -> bool` — озвучивание текста
  - `text` — текст для озвучки (максимум 4096 символов)
  - `voice` — голос ("alloy", "ash", "ballad", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer", "verse")
  - `path` — путь для сохранения файла
  - **Возвращает:** True при успешном сохранении, False при ошибке

---

### ChatGPT

Класс для работы с любым API, совместимым с OpenAI.

**Конструктор:**

- `__init__(url: str, headers: dict)` — создаёт экземпляр
  - `url` — базовый URL API
  - `headers` — заголовки для запросов

**Методы:**

- `generate_chat_completion(model: str, messages: list, temperature: float = None, max_tokens: int = None, stream: bool = False, **kwargs) -> Union[dict, list]` — генерация чат-ответа
  - `model` — модель
  - `messages` — сообщения
  - `temperature` — температура генерации
  - `max_tokens` — максимальное количество токенов
  - `stream` — потоковая передача
  - **Возвращает:** ответ API

- `generate_image(prompt: str, n: int = 1, size: str = "1024x1024", response_format: str = "url", **kwargs) -> dict` — генерация изображения
  - `prompt` — описание изображения
  - `n` — количество изображений
  - `size` — размер ("1024x1024", "1024x1792", "1792x1024")
  - `response_format` — формат ответа ("url" или "b64_json")
  - **Возвращает:** ответ API

- `generate_embedding(model: str, input_i: Union[str, list], user: str = None, **kwargs) -> dict` — генерация эмбеддингов
  - `model` — модель
  - `input_i` — текст или список текстов
  - `user` — пользователь (опционально)
  - **Возвращает:** ответ API

- `generate_transcription(file: BinaryIO, model: str, language: str = None, prompt: str = None, response_format: str = "json", temperature: float = 0, **kwargs) -> Union[dict, str]` — транскрибация аудио
  - `file` — аудиофайл
  - `model` — модель
  - `language` — язык
  - `prompt` — подсказка
  - `response_format` — формат ответа
  - **Возвращает:** транскрипцию

- `generate_translation(file: BinaryIO, model: str, prompt: str = None, response_format: str = "json", temperature: float = 0, **kwargs) -> Union[dict, str]` — перевод аудио
  - `file` — аудиофайл
  - `model` — модель
  - `prompt` — подсказка
  - `response_format` — формат ответа
  - **Возвращает:** перевод

- `get_models()` — получение списка моделей
  - **Возвращает:** список моделей из API

---

## 🔒 Лицензия

MIT License

## 📫 Обратная связь

Email: **siriteamrs@gmail.com**

Если возникнут идеи, баги, предложения — пишите 🙌
