selectel-ml-tui

TUI-приложение (Python 3.10+) для отображения потребления ИИ-роутера Selectel прямо в терминале. Работает на Ubuntu (22.04+/24.04) и macOS (12+).

Возможности

• Дашборд потребления за месяц (сумма, запросы, input/output/cache токены)
• Метрики за 24 часа (доступность, TTFT, задержка) — общие и по моделям
• Бюджет роутера (лимит/расход/остаток) и лимиты по API-ключам
• История потребления по дням с Unicode-бар-графиком (локальный SQLite-кэш)
• Детализация метрик конкретной модели (Enter в таблице моделей)
• Офлайн-режим: при недоступности API показывает последние данные из кэша
• Автообновление по интервалу из конфигурации (по умолчанию 60 с)
• Экспорт истории в CSV/JSON, диагностика окружения (doctor)

Интерфейс

┌─ Selectel ML Tokens ──────────────── online · 1 186,73 ₽ ───────┐
│ ┌─ Потребление за месяц ─┐ ┌─ Метрики за 24 часа ──────────────┐ │
│ │ Сумма: 1 186,73 ₽      │ │ Доступность: 100,0%              │ │
│ │ Запросы: 1 096         │ │ TTFT: 3 670,0 мс                 │ │
│ │ Токены: 482 749 246    │ │ Запросы: 1 097                   │ │
│ │ Input: 244 004 716     │ │ Input/Output/Cache: …            │ │
│ │ Output/Cache: …        │ └───────────────────────────────────┘ │
│ │ Бюджет: 2 000 ₽        │                                      │
│ └────────────────────────┘                                      │
│ По моделям                                                      │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Модель │ Запросы │ Доступность │ TTFT, мс │ Задержка, мс    │ │
│ │ deepseek-v4-pro │ 1028 │ 100,0% │ 3,69 │ 12,29              │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ r — обновить  h — история  k — ключи  s — настройки  q — выход   │
└──────────────────────────────────────────────────────────────────┘

Экран История (h): бар-график стоимости по дням + таблица (период 7/30/90 дней — кнопками). Экран Ключи (k): лимиты и расход по API-ключам. Экран Настройки (s): интервал обновления, «Очистить кэш», пути и маскированный токен. Esc — назад.

Горячие клавиши

Клавиша	Действие
r	Обновить данные
h	История потребления
k	API-ключи и лимиты
s	Настройки
q	Выход
Esc	Назад (с экрана истории/настроек/модели)
Enter / клик	Детализация метрик модели (в таблице «По моделям»)

На macOS горячие клавиши — обычные символьные (r/h/s/q); Option/Command зарезервированы системой и не используются.

Требования

• Python 3.10+
• Ubuntu 22.04+/24.04, macOS 12+
• Терминал с поддержкой цвета и UTF-8 (GNOME Terminal, Konsole, tmux, Terminal.app, iTerm2)

Источники данных

• Billing Statistics API (https://api.selectel.ru, заголовок X-Token): стоимость потребления ИИ-роутера (провайдер aig) по дням/часам. Параметры start/end принимаются в полном ISO-формате (YYYY-MM-DDTHH:MM:SS.000), короткие даты дополняются клиентом автоматически. Значение value в копейках.
• Gateway API ИИ-роутера (/aig/gateway/v1/*, IAM-токен проекта + X-Project-Id): токены, метрики, каталог моделей.
• IAM-авторизация: POST https://cloud.api.selcloud.ru/identity/v3/auth/tokens (логин/пароль сервисного пользователя, scope project, TTL 24 ч, кэш с автообновлением за 5 минут до истечения).

Получение токенов (панель Selectel)

• Статический токен (billing-метрики): панель my.selectel.ru → профиль → Доступ → API-ключи. Вставьте токен в мастер настройки.
• IAM-токен (gateway: сумма/токены/модели/ключи): нужен сервисный пользователь. Создайте его в my.selectel.ru → IAM → Сервисные пользователи (имя без email, например ml-monitor), назначьте роль на нужный ML-проект. Затем в selectel-ml-tui config укажите имя сервисного пользователя, его пароль, project_id и domain_id (номер аккаунта). Без сервисного пользователя доступна только стоимость из billing.

Подробнее об API: Selectel ML / управление роутером — внутренние API панели и документация по биллингу.

Установка

make install          # Ubuntu/macOS
# или
./scripts/install_ubuntu.sh   # Ubuntu
./scripts/install_macos.sh    # macOS
# или make install-ubuntu / make install-macos

Всё сводится к двум командам на каждой ОС:

# Ubuntu
sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip
pip install --user .          # или ./scripts/install_ubuntu.sh

# macOS
brew install python@3.11      # или ./scripts/install_macos.sh
pip install --user .

Запуск

make run
# или
.venv/bin/selectel-ml-tui run
# или (с корректным TERM/LANG, подходит для tmux/ssh)
./scripts/run.sh run

CLI-точка входа: selectel-ml-tui (console_scripts), а также python -m selectel_ml_tui.

При первом запуске без настроенных учётных данных выводится подсказка (selectel-ml-tui config); selectel-ml-tui doctor предупреждает, что токен не настроен.

TUI-дашборд:

• Dashboard: потребление за месяц (сумма, токены), метрики за 24 часа, таблица «По моделям»; статус в заголовке — online/offline
• r — обновить, h — история, s — настройки, q — выход
• Автообновление по интервалу из конфигурации (по умолчанию 60 с)
• При недоступности API показывает последние данные из кэша (офлайн)
• История (h): таблица по дням из кэша + Unicode-бар-график стоимости, выбор периода 7/30/90 дней (кнопки)
• Модель (Enter/клик в таблице моделей): детализация метрик конкретной модели
• Настройки (s): изменение интервала обновления (сохранение в конфиг), «Очистить кэш», пути к конфигу/БД, маскированный токен
• Навигация: Esc — назад

Конфигурация

selectel-ml-tui config           # интерактивный мастер настройки
selectel-ml-tui config --path    # показать пути конфигурации
selectel-ml-tui config --show    # показать текущие настройки (секреты маскируются)

Настройки хранятся в config.toml, учётные данные (пароль сервисного пользователя, статический токен) — в credentials.json в каталоге конфигурации (права 0600). Каталог: Linux — ~/.config/selectel-ml-tui, macOS — ~/Library/Application Support/selectel-ml-tui.

Переменные окружения имеют приоритет над файлом конфигурации:

• SELCTEL_API_URL — базовый URL API (вместо api_base_url)
• SELCTEL_TOKEN — статический токен (вместо static_token)
• SELCTEL_SERVICE_USER, SELCTEL_PASSWORD — сервисный пользователь
• SELCTEL_PROJECT_ID, SELCTEL_DOMAIN_ID — проект и аккаунт
• остальные поля: SELCTEL_API_BASE_URL, SELCTEL_REFRESH_INTERVAL, SELCTEL_ROUTER_ID, …

Локальный кэш и история

Данные сохраняются в SQLite-базу (cache.db) в каталоге данных платформы (Linux: ~/.local/share/selectel-ml-tui, macOS: ~/Library/Application Support/selectel-ml-tui) при каждом успешном обновлении:

• consumption_snapshots — снимки потребления (сумма, токены)
• metrics_snapshots — снимки общих метрик
• model_metrics — метрики по моделям
• history — точки истории по периодам (upsert, без дублей)

При недоступности API TUI показывает «офлайн» и последние данные из кэша. Старые записи удаляются автоматически (TTL 180 дней).

Экспорт истории: selectel-ml-tui export --format json|csv -o <файл>.

Платформы (Ubuntu и macOS)

Диагностика окружения: selectel-ml-tui doctor — проверяет Python (>=3.10), TERM, LANG, кодировку UTF-8, выводит пути к конфигурации и данным.

Отличия платформ:

	Ubuntu 22.04+/24.04	macOS 12+
Python	python3.10+ (apt: python3 python3-venv python3-pip)	Homebrew python@3.11+
Каталог конфигурации	~/.config/selectel-ml-tui	~/Library/Application Support/selectel-ml-tui
Каталог данных	~/.local/share/selectel-ml-tui	~/Library/Application Support/selectel-ml-tui
Права доступа	0700/0600 (по умолчанию)	то же; доступ на чтение к Application Support
Терминалы	GNOME Terminal, Konsole, tmux	Terminal.app, iTerm2
Клавиши	—	hotkeys через Ctrl/символы (r/h/s/q); Option/Command зарезервированы системой

Требования к окружению терминала:

• TERM должен указывать на цветной терминал (xterm-256color, tmux-256color). В tmux/screen задаётся автоматически; scripts/run.sh подставляет xterm-256color, если переменная не задана.
• LANG/locale должны быть UTF-8 (ru_RU.UTF-8, en_US.UTF-8), иначе возможны сбои отображения русского текста и граничных символов (▌▀█).

CI: GitHub Actions (ubuntu-latest + macos-latest, Python 3.11/3.12) — ruff, mypy, pytest+coverage, doctor.

Упаковка (однофайловый исполняемый файл)

Опционально: сборка автономного бинарника через PyInstaller.

make build                      # или ./scripts/build_ubuntu.sh / build_macos.sh
./dist/selectel-ml-tui doctor   # проверка

Артефакт не зависит от установленного Python и venv (собирается на целевой ОС).

История версий: CHANGELOG.md. Финальный чек-лист тестирования: docs/FINAL_CHECKLIST.md.

Разработка

make test         # pytest + coverage (порог 80%)
make lint         # ruff (flake8/isort/format)
make typecheck    # mypy (strict)
make format       # ruff format

• Unit-тесты: config (приоритет env), storage, models (парсинг/форматирование), API-клиент (httpx.MockTransport: успех, 401, 429, 500, timeout, сетевые ошибки)
• Интеграционный smoke-тест TUI: headless-запуск приложения через App.run_test()
• Статический анализ настроен в pyproject.toml ([tool.ruff], [tool.mypy], fail_under = 80).

FAQ и troubleshooting

«Учётные данные не настроены» при запуске Выполните selectel-ml-tui config — мастер настройки запросит токен (и опционально сервисного пользователя для метрик моделей). Проверка: selectel-ml-tui doctor → [OK] token.

Ошибки авторизации (401 / 403)

• Статический токен истёк или неверен — получите новый в панели Selectel (профиль → API-токены) и обновите через selectel-ml-tui config.
• IAM-доступ: сервисный пользователь должен иметь роль reader на нужном ML-проекте; проверьте project_id и domain_id (аккаунт). У IAM-токена TTL 24 ч — приложение обновляет его автоматически (за 5 минут до истечения).

В дашборде нет метрик по моделям (Input/Output/Cache отсутствуют) Gateway-данные (токены по моделям, каталог моделей) требуют IAM-токена сервисного пользователя. Если сервисный пользователь не создан, доступна только стоимость (billing) — на дашборде выводится пояснение «Токены и модели — только через IAM». Создать сервисного пользователя: my.selectel.ru → IAM → Сервисные пользователи (с областью доступа на нужный проект), затем selectel-ml-tui config.

PermissionError при запуске (credentials.json не читается) Файлы конфигурации должны принадлежать текущему пользователю (права 0600). Если запускать приложение от root/sudo, файлы создаются с владельцем root, и обычный запуск падает. Исправление (macOS/Linux): sudo chown -R $USER ~/Library/Application\ Support/selectel-ml-tui (на Linux путь ~/.config/selectel-ml-tui). Не запускайте приложение от root.

Ошибка 422 при запросе данных API принимает только полные ISO-таймстампы (YYYY-MM-DDTHH:MM:SS.000). Приложение формирует их самостоятельно; если ошибка повторяется — проверьте часовой пояс (doctor → LANG/locale).

«Краказябры»/битые символы в терминале LANG/locale должны быть UTF-8 (ru_RU.UTF-8, en_US.UTF-8), TERM — цветной (xterm-256color). Запуск через ./scripts/run.sh run подставит значения автоматически (полезно в tmux/ssh).

Офлайн-режим При недоступности API в заголовке появляется offline, а дашборд показывает последние снимки из SQLite-кэша. Данные обновятся автоматически при восстановлении сети (клавиша r — вручную).

«Нет данных для графика» в истории Кэш пуст — данные появляются после первого успешного обновления (каждая загрузка сохраняет точку за день). Очистить кэш можно в экране «Настройки» или через export (не очищает).