MGost

Библиотека позволяет пользоваться преимуществами MGost конвертера локально

Для ИИ-агентов / For AI agents: справочник по синтаксису Markdown, макросам и CLI MGost — https://articha.ru/static/mgost_conv/llms.md

Установка

Для начала необходимо получить API токен на официальном сайте конвертера

После создания ключа можно запустить библиотеку напрямую через uv (Рекомендуется):

uvx -p 3.13 mgost version

Или через pip:

python3.13 -m pip install mgost
python3.13 -m mgost version

Запуск

Для инициализации папки для проекта используйте mgost init. Первый запуск запросит API токен:

$ uvx -p 3.13 mgost init
API ключ не найден ни в переменных среды, ни в .env.
Введите код вручную или внесите его в вышеперечисленные источники
ARTICHAAPI_TOKEN=

После ввода токена, нужно выбрать проект:

ARTICHAAPI_TOKEN= ...
Текущий проект недействительный в облаке. Воспользуйтесь mgost init для инициализации проекта
Создать новый проект или синхронизировать существующий?
0. Создать новый проект
1. "Проект1"
2. "Проект2"
Действие: 

В зависимости от выбора, могут быть другие вопросы инициализации

Синхронизация

После инициализации проект можно синхронизировать и выполнять рендер. Команда mgost render синхронизирует проект с облаком и выполнит рендер.

$ mgost render
Текущий проект: Проект1
Синхронизация ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3/3
Начинаю рендер
Рендер успешно завершён
↓ output.docx ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

В случае проблем с выполнением рендера, лог будет отображаться в консоли:

$ mgost render
Текущий проект: Проект1
Синхронизация ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3/3
Начинаю рендер
Рендер успешно завершён
    ИНФО: grafana-logo-3.png не существует. Изображение (рисунок) пропущен
↓ output.docx ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00

Быстрая конвертация

mgost convert конвертирует один markdown в .docx без проекта, синхронизации и mgost init. Локальные файлы (изображения и т.д.) при этом не загружаются. Результат занимает то же место, что и быстрая конвертация на сайте.

$ mgost convert                    # main.md → main.docx
$ mgost convert notes.md           # notes.md → notes.docx
$ mgost convert notes.md -o out/report.docx
$ cat notes.md | mgost convert - -o - > notes.docx

Токен берётся из ARTICHAAPI_TOKEN или .mgost/.env, иначе запрашивается. Введённый токен можно сохранить в .mgost/.env текущей папки. При чтении из stdin токен не запрашивается.

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

src/mgost/
├── __main__.py               # Точка входа для `python -m mgost`
├── console.py                # Обёртка над typer/click для консольного вывода (прогресс, цвета, промпты)
├── api/
│   ├── api.py                # Класс ArtichaAPI — HTTP-клиент для работы с облаком (проекты, файлы, токены)
│   ├── actions.py            # Датаклассы действий синхронизации (загрузка/скачивание/перемещение файлов)
│   ├── caller.py             # Низкоуровневая функция выполнения HTTP-запроса с повторами
│   ├── exceptions.py         # Исключения API (WrongToken, ClientClosed, APIRequestError)
│   ├── remote_version.py     # Получение актуальной версии пакета с PyPI
│   ├── request.py            # Датакласс APIRequestInfo — описание одного запроса
│   └── schemas/
│       ├── general.py        # Общие Pydantic-схемы (TokenInfo)
│       └── mgost.py          # Pydantic-схемы предметной области (Project, ProjectFile, BuildResult и т.д.)
├── cli/
│   ├── app.py                # Создание typer.Typer приложения и обёртка main() с перехватом Ctrl+C
│   ├── callback.py           # Глобальный callback CLI (флаг -v, инициализация логирования)
│   ├── commands.py           # Определения команд CLI (version, token, init, sync, render, convert)
│   └── async_commands.py     # Асинхронные реализации команд CLI
├── mgost/
│   ├── mgost.py              # Класс MGost — основной фасад: инициализация, синхронизация, рендер проекта
│   ├── fast_convert.py       # Быстрая конвертация одного markdown без проекта (`mgost convert`)
│   ├── sync.py               # Логика синхронизации файлов проекта с облаком
│   ├── progress_utils.py     # Кастомные колонки rich.progress (например, отображение байт/штук)
│   └── utils.py              # Вспомогательные функции (валидация токена и проекта, вывод логов рендера)
└── settings/
    ├── settings.py           # Класс Settings — чтение токена/конфига из env, .env, команды
    └── logging.py            # Настройка логирования
tests/                        # Тесты (pytest), структура повторяет src/mgost