GraphStudio — CMDB Graph Designer

Интерактивный веб-инструмент для проектирования и визуализации CMDB-графов (типов и объектов) с LLM-генерацией шаблонов по текстовому описанию системы.

GraphStudio помогает спроектировать двухуровневую модель конфигурационной базы данных (CMDB): сначала описывается граф типов (классы сущностей, их атрибуты и допустимые связи), затем — граф объектов (конкретные экземпляры, связи которых проверяются по правилам типового графа). Инструмент задуман как удобная «песочница» для быстрого наброска таких графов и экспорта их в JSON.

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

• Двухуровневая модель — отдельные графы типов и объектов с проверкой допустимости связей объектов по типовому графу.
• Редактор «вживую» — drag-n-drop узлов и связей, контекстное меню, панель редактирования имён и атрибутов.
• Галерея шаблонов — готовые графы (Kubernetes, Docker, PostgreSQL, Redfish, IPMI, Corosync и др.) загружаются в один клик.
• Импорт / экспорт JSON — состояние графа выгружается и загружается как обычный файл.
• AI-генерация — встроенный чат с OpenAI генерирует структуру графа по описанию системы; кнопка «Загрузить в граф» появляется только если ответ проходит структурную валидацию.
• Без сборки фронтенда — vanilla JS + vis-network, запуск одной командой.

🏗 Архитектура

Слой	Технологии
Backend	FastAPI + Uvicorn (REST API: загрузка/сохранение графа, список шаблонов, прокси к LLM)
Frontend	Vanilla JavaScript, vis-network для рендеринга графов, шрифт Manrope
LLM	OpenAI API (AsyncOpenAI) со скрытым системным промптом (utils/prompts.py)
Конфигурация	.env (python-dotenv) — ключ API и параметры модели

Browser (vis-network, app.js)
        │  REST /api/{load,save,templates,chat}
        ▼
FastAPI (main.py) ──► OpenAI API (только для /api/chat)
        │
        ▼
graph_templates/  (JSON + превью, отдаются как статика)

🚀 Быстрый старт

# 1. Клонировать репозиторий
git clone https://github.com/HpPpL/cmdb-graph-studio.git
cd cmdb-graph-studio

# 2. Установить зависимости
make init-deps

# 3. (Опционально, нужно только для AI-чата) задать ключ OpenAI
cp .env.example .env
#   и прописать в .env свой API_KEY=...

# 4. Запустить сервис
make run-service

Откройте http://localhost:8000. Приложение полностью работает и без ключа — недоступна только AI-генерация (чат вернёт понятную ошибку).

🧩 Как пользоваться

• Шаблоны — кнопка «Шаблоны» в шапке открывает галерею; клик по превью загружает граф.
• Редактирование — ПКМ по полю графа открывает меню (добавить тип/объект, импорт/экспорт); потяните от одного узла к другому, чтобы создать связь. Для объектов связь разрешена только если она есть в графе типов.
• Импорт / Экспорт — кнопки в шапке выгружают текущий граф в graph-export.json и загружают граф из файла.
• AI-генерация — кнопка «AI-генерация» открывает чат. Опишите систему — ассистент вернёт JSON; если структура валидна, появится кнопка «Загрузить в граф».

AI-генерация в действии

Опишите систему словами	Получите граф и загрузите одним кликом

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

Все настройки берутся из .env (см. .env.example):

Переменная	По умолчанию	Назначение
API_KEY	—	Ключ LLM-провайдера. Без него работает всё, кроме /api/chat.
LLM_BASE_URL	OpenAI	Endpoint провайдера. Пусто → OpenAI; можно указать любой OpenAI-совместимый.
LLM_MODEL	gpt-4.1	Id модели (должен поддерживаться выбранным провайдером).
LLM_MAX_TOKENS	10000	Лимит токенов ответа.
LLM_TEMPERATURE	0.7	Температура генерации.

Приложение использует OpenAI SDK, поэтому подойдёт любой OpenAI-совместимый провайдер — достаточно задать LLM_BASE_URL, API_KEY и LLM_MODEL. Например, бесплатная модель через OpenRouter:

API_KEY=sk-or-v1-...
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=qwen/qwen3-next-80b-a3b-instruct:free

Так же подключаются Groq, Google AI Studio, локальный Ollama/LM Studio и т.п. — см. примеры в .env.example.

📁 Структура репозитория

.
├── main.py                  # FastAPI-приложение и REST API
├── utils/prompts.py         # системный промпт для LLM
├── templates/index.html     # разметка приложения
├── static/                  # CSS, JS и изображения фронтенда
│   ├── css/style.css
│   ├── js/app.js
│   └── images/
├── graph_templates/         # ШТАТНЫЕ шаблоны, которые отдаёт приложение
│   ├── templates/           #   граф в формате JSON
│   └── assets/              #   превью-картинки
└── examples/llm-generated/  # ПРИМЕРЫ графов, сгенерированных разными LLM
    ├── claude/              #   (не используются в рантайме — это бенчмарк,
    ├── deepseek/            #    см. examples/llm-generated/README.md)
    └── grok/

graph_templates/ vs examples/llm-generated/: первое — кураторские шаблоны, которые приложение показывает в галерее. Второе — демонстрационный набор «как разные модели генерируют граф из одинаковых промптов»; в рантайме он не задействован, но любой файл можно открыть через Импорт.

🗒 Замечания и ограничения

• Состояние графа хранится в памяти процесса (одна глобальная переменная в main.py) — это однопользовательская демо-«песочница». При перезапуске сервера граф сбрасывается; для нескольких пользователей состояние общее. Сохраняйте важные графы через Экспорт.
• Системный промпт и параметры модели рассчитаны на формат графа GraphStudio (types / objects).

🩺 Troubleshooting

Симптом	Причина / решение
Чат отвечает «LLM is not configured…»	Не задан API_KEY в .env. Это ожидаемое поведение — добавьте ключ и перезапустите сервис.
Чат отвечает «LLM request failed…»	Ошибка на стороне OpenAI (неверный ключ, лимиты, сеть). Подробности — в логах сервера.
Кнопка «Загрузить в граф» не появляется	Ответ LLM не содержит валидного JSON со структурой { "types": [...], "objects": [...] }.
Граф пустой после перезапуска	Состояние в памяти сбрасывается — это by design, см. «Ограничения».
make: command not found	Запустите напрямую: pip install -r requirements.txt, затем uvicorn main:app --reload.

🔐 Безопасность

• Файл .env и любые ключи не коммитятся — он добавлен в .gitignore. В репозитории лежит только безопасный .env.example с плейсхолдером.
• API-ключ читается из окружения и никогда не отдаётся клиенту.

📜 Лицензия

См. LICENSE.