Перейти к основному содержимому

Введение в Hyper Stack Manager (hsm)

hsm — это Meta-Orchestrator для современной разработки, выступающий в роли "Environment Hypervisor". Он позволяет декларативно собирать рабочее окружение проекта из независимых компонентов (Python-пакетов и Docker-контейнеров) на основе единого манифеста hsm.yaml.

Внимание

Проект находится на самой ранней стадии разработки (Alpha). Возможны критические изменения API и структуры манифестов между версиями.

HSM решает проблему управления сложными, модульными системами, предоставляя уровень абстракции над инструментами (uv, docker).

Основные концепции​

1. Декларативность (Declarative Intent)​

В отличие от императивных команд установки, HSM использует файл hsm.yaml как единственный источник правды (Source of Truth). Разработчик описывает что он хочет видеть в проекте, а HSM берет на себя задачу как это реализовать.

2. Мета-оркестрация и Адаптеры​

HSM не заменяет существующие инструменты, а оркестрирует их через систему адаптеров:

  • Python Adapter (uv): Управляет зависимостями в pyproject.toml.
  • Docker Adapter: Управляет сервисами через генерацию docker-compose.hsm.yml.

3. Гибридное окружение (Hybrid Stack)​

HSM позволяет одновременно управлять и библиотечным кодом, и инфраструктурными сервисами. Это обеспечивает бесшовную интеграцию: например, вы выбираете в манифесте реализацию векторной БД, и HSM одновременно подтягивает нужный Python-клиент и разворачивает соответствующий контейнер.

4. Режимы Dev vs Prod​

HSM нативно поддерживает переключение режимов:

  • Prod: Использует стабильные артефакты (PyPI пакеты, готовые Docker-образы).
  • Dev: Переключает компоненты на локальные исходники (Editable installs для Python, build контексты и volumes для Docker).

5. Умный выбор (1-of-N / M-of-N)​

Механизм групп в Реестре позволяет определять интерфейсы. Пользователь выбирает одну из нескольких реализаций (например, Qdrant vs Milvus), и HSM автоматически перестраивает всё окружение под этот выбор.

Ключевые преимущества​

  • Atomic Sync: Изменения применяются транзакционно. Если зависимости не сошлись (например, ошибка в uv sync), основные конфиги проекта (pyproject.toml, docker-compose.yml) остаются нетронутыми.
  • LEGO-принцип: Каждый компонент является заменяемым кирпичиком с четким интерфейсом.
  • No Hard Dependencies: Избавляет от git submodules. Код плагинов подтягивается динамически только тогда, когда он нужен.
  • Unified DX: Единый CLI для управления всем стеком технологий проекта (Python + Docker Compose).