max-shared

Общая библиотека для проектов MAX Hermes

Shared-модули: MAXClient, Pydantic-модели, конвертер сообщений, утилиты markdown

🇷🇺 Российская разработка Open source · MIT

⚡ Единый код для bridge и plugin Устраняет дублирование между проектами

---

📋 Содержание

• О проекте
• Модули
• Установка
• Использование
• API клиент (MAXClient)
• Pydantic-модели
• Конвертер сообщений
• История изменений
• Лицензия

---

📘 О проекте

max-shared — общая библиотека, используемая в двух продуктах:

Проект	Описание	Тип
max-hermes	Самодостаточный мост-демон (aiohttp + Hermes CLI)	standalone
max-hermes-plugin	Нативный платформенный плагин для Hermes Gateway	plugin

Библиотека устраняет дублирование кода — модели запросов/ответов MAX Bot API, HTTP-клиент и конвертер живут в одном месте.

📦 Модули

Модуль	Назначение
constants	Константы: URL API, таймауты, лимиты, типы обновлений
models	Pydantic-модели для MAX Bot API (update, message, attachment)
max_client	Асинхронный HTTP-клиент для MAX Bot API
converter	Конвертер между форматами MAX API и внутренним представлением
markdown	Детектирование и очистка markdown-форматирования

🔧 Установка

pip install -e /path/to/max-shared

Или в requirements.txt:

max-shared @ file:///path/to/max-shared

🚀 Использование

from max_shared.max_client import MAXClient
from max_shared.converter import MessageConverter
from max_shared.markdown import has_markdown

# API клиент
client = MAXClient(token="your-bot-token")
bot_info = await client.get_bot_info()

# Конвертер
payload = MessageConverter.max_update_to_message(update)
max_msg = MessageConverter.response_to_max_message(response, user_id=123)

# Markdown
if has_markdown(text):
    payload["format"] = "markdown"

🎛️ API клиент (MAXClient)

Основные методы

Метод	Описание
get_bot_info()	Получить информацию о боте
send_message(chat_id, text, ...)	Отправить сообщение
edit_message(message_id, chat_id, text, ...)	Редактировать сообщение
delete_message(message_id, chat_id)	Удалить сообщение
send_action(chat_id, action)	Индикатор «Печатает...»
set_commands(commands)	Зарегистрировать команды бота (NEW)
upload_file(file_path, file_name)	Загрузить файл для отправки
send_file(chat_id, file_id, ...)	Отправить файл
create_subscription(url, secret)	Зарегистрировать webhook
get_subscriptions()	Получить список webhook
delete_subscription(id)	Удалить webhook
get_updates(params)	Получить новые события (long polling)

set_commands()

# Зарегистрировать команды для меню бота
await client.set_commands([
    {"name": "start", "description": "Начать диалог с ботом"},
    {"name": "help", "description": "Помощь и информация о боте"},
    {"name": "about", "description": "О боте и его возможностях"},
])

# Удалить все команды
await client.set_commands([])

Команды отправляются на PATCH /me/commands через COMMANDS_API_BASE_URL (https://platform-api2.max.ru).

📐 Pydantic-модели

Модель	Описание
Update	Входящее событие от MAX API
Message	Сообщение (текст, attachments, кнопки)
Attachment	Вложение (изображение, видео, аудио, файл)
Button	Кнопка в inline keyboard
Callback	Callback от нажатой кнопки
Recipient	Получатель сообщения
Sender	Отправитель сообщения

🔄 Конвертер сообщений

Метод	Описание
max_update_to_message(update)	MAX webhook → внутренний словарь
response_to_max_message(response, ...)	Ответ Hermes → MAX формат

📄 История изменений

#	Изменение	Файл
1	set_commands() — новый метод для регистрации команд бота через PATCH /me/commands	max_client.py
2	COMMANDS_API_BASE_URL — новая константа https://platform-api2.max.ru для commands API	constants.py
3	attachments → Optional — Pydantic v2 больше не падает на null от MAX	models.py

📄 Лицензия

MIT

---

🔗 Связанные проекты

Проект	Описание
max-hermes	Standalone bridge daemon — webhook, Docker, systemd
max-hermes-plugin	Native Hermes Agent platform plugin

---

_{🇷🇺 Опенсорс — Поддержи наш продукт · BR-DESIGN}