upload

docs/README.md

@@ -0,0 +1,409 @@
+# ML Core Swagger (Сдача)
+
+Актуальный сдаваемый Swagger для ML core backend лежит в файле:
+
+- `docs/ml_core_backend_openapi.yaml`
+
+Что входит в документ:
+
+- `POST /api/v1/pipelines/generate`
+- `GET /api/v1/pipelines/dialogs`
+- `GET /api/v1/pipelines/dialogs/{dialog_id}/history`
+- `POST /api/v1/pipelines/dialog/reset`
+- `POST /api/v1/pipelines/{pipeline_id}/run`
+- `GET /api/v1/executions`
+- `GET /api/v1/executions/{run_id}`
+
+Что не входит в этот документ:
+
+- auth, actions, capabilities ручки
+- demo `/ml/*` ручки из `demo-backend/openapi/*`
+
+Быстрая проверка локально:
+
+```bash
+cd backend
+pytest -s --capture=no tests/test_ml_openapi_contract.py
+```
+
+Дополнительная валидация OpenAPI (если установлен валидатор):
+
+```bash
+python3 -m openapi_spec_validator docs/ml_core_backend_openapi.yaml
+```
+
+---
+
+# AI Copilot
+## Core Concept
+    Главная задача проекта: Трансформация статической документации API в автономную интеллектуальную систему. Пользователь предоставляет набор OpenAPI файлов и бизнес-логику, которую он хочет получить, чтобы протестировать, а система незамедлительно проектирует и исполняет готовые Pipelines для решения задачи.
+
+## The Value Chain
+### Action → Capability → Pipeline
+
+Система работает по принципу восходящей абстракции:
+
+- **Actions (Технический слой)**: Набор разрозненных эндпоинтов из OpenAPI.
+- **Capability (Логический слой)**: Группа из одного или нескольких Actions, объединенных общей бизнес-целью. Это абстракция для AI, который знает, как выполнить конкретную функцию.
+- **Pipeline (Сценарный слой)**: Последовательность из Capabilities, решающая задачу пользователя.задачу. | Итоговый план действий. |
+
+## ЦА — продакт менеджеры
+>**Проблема**: у продакт менеджеров есть гипотеза (например: «Если отправлять пуш тем, кто бросил корзину через 15 минут, конверсия вырастет»), но чтобы её проверить, нужно ставить задачу в спринт, ждать 2 недели и отвлекать бэкенд.
+
+>**Решение**: Наш AI-copilot позволяет проджект менеджеру предоставить системе API маркетинговой платформы и CRM, а затем автоматически создать и запустить Pipeline, решающий бизнес-задачу.
+
+## User stories
+Роль|Я хочу (Действие)|Чтобы (Ценность)|Definition of Done (Критерии приемки)|Модуль
+|---|---|---|---|---|
+PM|Загрузить файл OpenAPI (Swagger)|Система получила сырую базу технических методов (Actions).|Файл парсится, эндпоинты сохранены в БД.|Ingestion
+PM|Объединить несколько Actions в одну Capability|Скрыть техническую сложность и создать «навык» (напр. «Обновить профиль»).|В базе создана сущность Capability, связанная с 1+ Actions.|Capability
+PM|Получить авто-описание для Capability от AI|Не тратить время на ручное заполнение названий и смыслов для каждого навыка.|Каждой Capability присвоено человекочитаемое имя и описание.|Semantic
+PM|Описать бизнес-задачу в чате (напр. «Найди новичков и поздоровайся»)|AI-копилот сам подобрал нужные Capabilities и построил из них Pipeline.|AI выдает валидный JSON-граф с ID навыков и логическими связями.|Synthesis
+PM|Видеть сгенерированный сценарий в виде графа|Визуально подтвердить, что данные (напр. user_id) передаются верно.|На канвасе отрисованы ноды и стрелки (React Flow).|Synthesis
+PM|Вручную отредактировать параметры внутри ноды|Финальный сценарий на 100% соответствовал конкретной задаче.|Форма редактирования корректно сохраняет данные в объект ноды.|Execution
+PM|Подтвердить запуск Pipeline нажатием кнопки|Контролировать процесс и избежать случайных ошибок в реальных системах.|Запуск происходит только после клика; первая нода переходит в статус active.|Execution
+PM|Наблюдать за выполнением шагов в реальном времени|Видеть прогресс и понимать, на каком этапе сейчас находится выполнение.|Активная нода подсвечивается; статусы (Success/Fail) обновляются в UI.|Execution
+PM|Получить лог ответов от всех API по завершении|Убедиться, что гипотеза проверена и данные ушли/пришли корректно.|По завершении выводится панель с результатами (JSON-логи).|Execution
+
+## Domain layer
+Все сущности, покрывающие user-stories:
+
+Сущность|Что это|Зачем нужна
+|---|---|---|
+Action|Инструмент в ящике.|Хранит технические детали одного эндпоинта (URL, метод, JSON-схема).
+
+#### Что в модели Action:
+Поле|Тип|Назначение
+|---|---|---|
+id|UUID PK|Первичный ключ
+operation_id|String|operationId из OpenAPI
+method|HttpMethod enum|GET / POST / PUT / PATCH / DELETE …
+path|String|URL-путь, напр. /users/{id}
+base_url|String|Базовый URL из servers[] спецификации
+summary|String|Краткое описание из OpenAPI
+description|Text|Подробное описание из OpenAPI
+tags|JSON|Теги для группировки
+parameters_schema|JSON|JSON Schema query/path/header параметров
+request_body_schema|JSON|JSON Schema тела запроса
+response_schema|JSON|JSON Schema успешного ответа (2xx)
+source_filename|String|Имя загруженного Swagger-файла
+raw_spec|JSON|Оригинальный фрагмент операции из спецификации
+created_at / updated_at|DateTime|Через TimestampMixin
+
+
+Capability|Навык мастера.|Описывает бизнес-логику (связку 1+ Actions) и семантику для AI.
+Node|Шаг в инструкции.|Конкретный блок в графе. Ссылается на Capability, но хранит индивидуальные настройки (например, текст письма именно для этого шага).
+Pipeline|Инструкция (чертеж).|Коллекция нод и связей между ними. Хранит общую структуру графа.
+
+#### Что в модели Pipeline:
+Поле|Тип|Назначение
+|---|---|---|
+id|UUID PK|Первичный ключ
+name|String|Название пайплайна
+description|Text|Описание сценария
+user_prompt|Text|Оригинальный промпт PM из чата
+nodes|JSON|Список нод графа с параметрами и позициями
+edges|JSON|Список рёбер графа и порядка выполнения
+status|PipelineStatus enum|Статус пайплайна: DRAFT / READY / ARCHIVED
+created_by|UUID FK|Ссылка на пользователя-автора
+created_at / updated_at|DateTime|Через TimestampMixin
+
+Execution (Run)|Процесс сборки.|Хранит статус конкретного запуска (ID, время старта, текущий статус всего процесса).
+Context|Рабочая память.|Временный объект внутри Execution, где лежат результаты выполненных нод для подстановки в следующие.
+
+## Infrastructure layer
+Компонент|Технология|Роль и описание
+|---|---|---
+Database|PostgreSQL|Хранение структурированных данных (Actions, Capabilities, Pipelines).
+LLM Inference|vLLM / TGI (Text Generation Inference)|Хостинг твоей модели (Llama-3, Mistral и др.). Предоставляет высокопроизводительный OpenAI-совместимый API.
+ORM|SQLAlchemy + Alembic|Асинхронный маппинг доменных моделей на таблицы БД и управление миграциями без даунтайма.
+Async Runtime|FastAPI + Uvicorn|Ядро монолита. Обработка запросов, управление жизненным циклом приложения и фоновыми задачами.
+HTTP Client|HTTPX (Async)|фНеблокирующие вызовы к твоей локальной модели и внешним API сервисов (Slack, CRM и т.д.) внутри ExecutionCore.
+Cache / State|Redis|Хранение промежуточного состояния (Context) активных пайплайнов и кэширование результатов инференса.
+Containerization|Docker & Compose|Изоляция сервисов (App, DB, Model Server) и их оркестрация одной командой.
+
+## Service layer
+Каждый сервис отвечает за свой этап жизненного цикла — от загрузки API до получения результата.
+1. `IngestionService`
+
+    Задача: **Обработка Swagger/OpenAPI.**
+
+    Инструменты: Библиотеки prance или openapi-spec-validator.
+
+    Логика: Принимает файл через UploadFile, парсит его и сохраняет в БД (PostgreSQL) список Actions.
+
+    Метод: `async def ingest_openapi(file: UploadFile) -> List[ActionDomain]: ...`
+
+2. `CapabilityService`
+
+    Задача: **Группировка и описание навыков.**
+
+    Инструменты: LangChain или просто прямой вызов OpenAI SDK.
+
+    Логика: Получает ID Actions, делает запрос к LLM для генерации описания Capability, сохраняет результат.
+
+    Метод: `async def create_capability(action_ids: list[UUID], name: str) -> CapabilityDomain: ...`
+
+3. `SynthesisService`
+
+    Задача: **Сборка Pipeline через LLM.**
+
+    Логика:
+    - Получает промпт от PM.
+   -  Выбирает подходящие Capability из библиотеки в БД.
+    - Формирует промпт для QWEN-2.5, чтобы она вернула JSON-структуру графа.
+
+    Метод: `async def synthesize_pipeline(user_query: str) -> PipelineDomain: ...`
+4. `ExecutionService`
+
+    Задача: **Асинхронное выполнение графа.**
+
+    Инструменты: httpx (асинхронный клиент для запросов).
+
+    Логика:
+    - Инициализирует Context (Pydantic модель).
+    - Проходит циклом по нодам Pipeline.
+    - Заменяет переменные (Variable Injection).
+    - Делает await client.request(...).
+  
+    Метод: `async def run_execution(pipeline_id: UUID) -> ExecutionResult: ...`
+
+## Api layer
+### Actions
+Загрузка и валидация Swagger/OpenAPI.
+Метод|Путь|Описание
+|---|---|---|
+POST|`/api/v1/actions/ingest`|Загрузка файла OpenAPI (Multipart form-data).
+GET|`/api/v1/actions`|Получение списка всех импортированных методов с фильтрацией.
+GET|`/api/v1/actions/{id}`|Детальная схема конкретного экшена.
+DELETE|`/api/v1/actions/{id}`|Удаление экшена (если API обновилось или метод больше не нужен).
+
+#### Пример запроса ingest
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/actions/ingest" \
+  -H "Accept: application/json" \
+  -F "file=@/app/examples/travel.yaml;type=application/yaml"
+```
+
+#### Пример ответа ingest
+
+```json
+{
+  "created_actions_count": 5,
+  "created_capabilities_count": 5,
+  "capabilities": [
+    {
+      "id": "7c1d5c9b-2c9d-4f1c-9d2e-4a8f3e1b7a11",
+      "action_id": "e4b0bcb6-6a8c-4b0a-8e18-3f44b5f7d1c2",
+      "name": "get_recent_users",
+      "description": "Get recent users for travel campaigns",
+      "input_schema": null,
+      "output_schema": {
+        "type": "object"
+      },
+      "data_format": {
+        "parameter_locations": ["query"],
+        "request_content_types": [],
+        "request_schema_type": null,
+        "response_content_types": ["application/json"],
+        "response_schema_types": ["object"]
+      },
+      "created_at": "2026-03-14T12:00:00Z",
+      "updated_at": "2026-03-14T12:00:00Z"
+    }
+  ]
+}
+```
+### Capabilities
+Превращаем API в способности
+Метод|Путь|Описание
+|---|---|---|
+POST|`/api/v1/capabilities/suggest`|AI-powered: Система анализирует Actions и предлагает логические связки.
+POST|`/api/v1/capabilities`|Создание навыка: связка 1+ Action ID, маппинг данных и описание.
+GET|`/api/v1/capabilities`|Список всех навыков для отображения в библиотеке на фронте.
+GET|`/api/v1/capabilities/{id}`|Посмотреть, из каких Actions состоит навык и как внутри ходят данные.
+DELETE|`/api/v1/capabilities/{id}`|Удаление навыка.
+### Pipelines
+Основная точка входа для чата и канваса (React Flow).
+Метод|Путь|Описание
+|---|---|---|
+POST|`/api/v1/pipelines/generate`|AI-powered: Промпт из чата -> AI подбирает Capabilities -> Возвращает JSON-граф.
+GET|`/api/v1/pipelines`|Список всех сохраненных или сгенерированных сценариев.
+GET|`/api/v1/pipelines/{id}`|Загрузка конкретного графа на канвас.
+PUT|`/api/v1/pipelines/{id}`|Сохранение ручных правок: если PM подвигал ноды или изменил параметры.
+DELETE|`/api/v1/pipelines/{id}`|Удаление сценария.
+
+#### Вызов чата: `POST /api/v1/pipelines/generate`
+
+Используйте один и тот же `dialog_id` для одной цепочки сообщений, чтобы сохранялся контекст.
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/pipelines/generate" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dialog_id": "11111111-1111-1111-1111-111111111111",
+    "message": "Нужно взять 30 последних пользователей, распределить по 5 отелям и отправить email-офферы",
+    "user_id": null,
+    "capability_ids": null
+  }'
+```
+
+#### Пример ответа чата
+
+```json
+{
+  "status": "ready",
+  "message_ru": "Пайплайн собран. Можно запускать.",
+  "chat_reply_ru": "Пайплайн собран. Можно запускать. План шагов: get_users_recent -> get_hotels_top -> post_segments_hotel.",
+  "pipeline_id": "7b17ac70-3f39-4e70-8f8a-4a2f1fd4ff7e",
+  "nodes": [
+    {
+      "step": 1,
+      "name": "get_users_recent",
+      "description": "Отбирает недавних пользователей для travel campaign.",
+      "input_connected_from": [],
+      "output_connected_to": [3],
+      "input_data_type_from_previous": [],
+      "external_inputs": [],
+      "endpoints": [
+        {
+          "name": "get_users_recent",
+          "capability_id": "c4be1e66-2e04-4c6f-8d8f-6f39f1f46087",
+          "action_id": "e4b0bcb6-6a8c-4b0a-8e18-3f44b5f7d1c2",
+          "output_type": "users[]"
+        }
+      ]
+    },
+    {
+      "step": 2,
+      "name": "get_hotels_top",
+      "description": "Получает список топовых отелей для офферов.",
+      "input_connected_from": [],
+      "output_connected_to": [3],
+      "input_data_type_from_previous": [],
+      "external_inputs": [],
+      "endpoints": [
+        {
+          "name": "get_hotels_top",
+          "capability_id": "470ae37e-029e-4c67-a293-acb848675d0b",
+          "action_id": "96f0bc8f-e294-46a9-9a0e-48e1b8f2a941",
+          "output_type": "hotels[]"
+        }
+      ]
+    }
+  ],
+  "edges": [
+    {
+      "from_step": 1,
+      "to_step": 3,
+      "type": "users"
+    },
+    {
+      "from_step": 2,
+      "to_step": 3,
+      "type": "hotels"
+    }
+  ],
+  "missing_requirements": [],
+  "context_summary": "Пользователь хочет собрать travel-рассылку из доступных capability."
+}
+```
+
+`status` может быть:
+- `ready` — граф построен, `pipeline_id/nodes/edges` заполнены.
+- `needs_input` — нужно уточнение или добавить Swagger/OpenAPI.
+- `cannot_build` — с текущими данными сценарий не собирается.
+
+#### Сброс диалога: `POST /api/v1/pipelines/dialog/reset`
+
+```bash
+curl -X POST "http://localhost:8000/api/v1/pipelines/dialog/reset" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dialog_id": "11111111-1111-1111-1111-111111111111"
+  }'
+```
+
+### Execution
+Запуск пайплайна.
+Метод|Путь|Описание
+|---|---|---|
+POST|`/api/v1/pipelines/{id}/run`|Запуск пайплайна. Создает объект Execution и запускает цикл выполнения.
+GET|`/api/v1/executions`|История всех запусков (кто, когда и с каким результатом запускал).
+GET|`/api/v1/executions/{run_id}`|Статус в реальном времени: Поллинг для фронта (какая нода сейчас горит зеленым).
+POST|`/api/v1/executions/{run_id}/approve`|Подтверждение «опасного» шага (если нода требует Approval).
+
+## CapabilityService
+Задача: Инкапсулировать один или несколько технических Actions (API-эндпоинтов) в единый, понятный для LLM и пользователя бизнес-навык (Capability).
+
+### Этап 1: Формирование связки (Action Binding)
+
+На вход сервис получает массив ID Actions и их порядковые номера. Сервис валидирует, что эти эндпоинты существуют в БД.
+
+**Внутренний маппинг:** Сервис принимает правила передачи данных между экшенами. Например, ответ от GET /users (поле user.id) должен лечь в тело запроса POST /emails (в поле recipient_id).
+
+**Абстракция входа/выхода:** Сервис вычисляет публичную схему навыка (Input/Output Schema). Он берет все обязательные параметры всех внутренних экшенов, вычитает из них те, которые закрыты внутренним маппингом, и формирует итоговый JSON Schema. Для внешнего мира этот навык теперь выглядит как одна функция.
+
+### Этап 2: Семантическое обогащение (LLM Summarization)
+
+Чтобы ИИ в будущем понимал, зачем нужен этот инструмент, сервис обращается к локальной LLM (vLLM/TGI).
+
+Промпт к LLM: Сервис отправляет системный промпт, содержащий URL-адреса, методы и JSON-схемы объединенных экшенов.
+
+Задача LLM: Сгенерировать:
+- Короткое название (например, create_refund_ticket).
+- Подробное описание (например, «Используется для создания заявки на возврат средств в Zendesk и проверки статуса транзакции в Stripe»).
+
+### Этап 3: Сохранение навыка в библиотеку
+
+Текстовое описание и название навыка сохраняются в PostgreSQL вместе с `input_schema` и `output_schema`.
+
+Этот шаг делает Capability доступной для последующей сборки пайплайнов без дополнительного индексационного слоя.
+
+## SynthesisService
+Задача: Принять текстовый запрос пользователя, найти подходящие инструменты (Capabilities) и собрать из них валидный направленный ациклический граф (DAG), готовый к исполнению.
+
+Этот сервис вызывается каждый раз, когда пользователь пишет промпт в чат. Время его работы напрямую влияет на UX, поэтому он должен быть оптимизирован под максимальную скорость.
+
+### Этап 1: Отбор доступных навыков (Capability Selection)
+
+Запрос пользователя (например, "Найди последние 5 оплаченных заказов и отправь их в канал #sales") сопоставляется с доступной библиотекой Capability.
+
+Сервис собирает релевантный список навыков из PostgreSQL и готовит их для контекста LLM.
+
+Результат: Вместо сотен API-методов, в prompt передаются только подходящие "строительные блоки" (например, search_orders и send_slack_message).
+
+### Этап 2: Сборка контекста для LLM (Prompt Engineering)
+
+Сервис формирует динамический промпт для генерации графа. В него вшиваются:
+
+Инструкция (System Message): Жесткие правила работы («Ты парсер. Возвращай только JSON. Не выдумывай ID навыков»).
+
+Библиотека инструментов: JSON-схемы найденных на предыдущем шаге Capabilities (их id, name, description и input_schema).
+
+Промпт пользователя: Оригинальный текст запроса.
+
+### Этап 3: Генерация графа (LLM Inference)
+
+Локальная LLM обрабатывает контекст и возвращает структуру пайплайна в строгом формате.
+
+LLM определяет узлы (Nodes) — какие навыки использовать.
+
+LLM определяет ребра (Edges) — в каком порядке их вызывать.
+
+LLM прописывает переменные (Variable Injection) — как данные перетекают между узлами, используя синтаксис шаблонизатора (например, {{node_1.output.orders_list}}).
+
+### Этап 4: Строгая валидация (Sanitization & DAG Check)
+
+LLM склонны к галлюцинациям, поэтому перед сохранением в базу SynthesisService проводит жесткую проверку полученного JSON:
+
+Schema Validation (Pydantic): Проверка, что структура ответа строго соответствует модели Pipeline.
+
+Capability Existence: Проверка, что все capability_id в узлах реально существуют в базе (LLM не выдумала несуществующий навык).
+
+DAG Validation (Топологическая сортировка): Граф проверяется на отсутствие циклов (A -> B -> C -> A), чтобы предотвратить бесконечное выполнение.
+
+Parameter Validation: Проверка, что все обязательные поля из input_schema каждого навыка либо заполнены статичными значениями, либо имеют ссылку-шаблон на предыдущий узел.
+
+Если граф проходит валидацию, он сохраняется в таблицу pipelines и отдается на фронтенд для визуализации на канвасе. Если валидация провалена — сервис просит LLM исправить ошибку (Retry Logic, максимум 2 попытки), передавая ей текст ошибки валидации.

docs/ml_core_backend_openapi.yaml

@@ -0,0 +1,944 @@
+openapi: 3.0.3
+info:
+  title: AI Copilot ML Core Backend API
+  version: 1.0.0
+  description: |
+    Сдаваемая спецификация ML core части реального backend.
+    Источник истины: текущие роуты FastAPI `/api/v1/pipelines*` и `/api/v1/executions*`.
+    Документ не включает auth/actions/capabilities endpoint'ы, кроме использования JWT bearer security.
+servers:
+  - url: http://localhost:8000
+tags:
+  - name: Pipelines
+    description: Генерация и управление pipeline-диалогом, запуск выполнения.
+  - name: Executions
+    description: История и детали запусков pipeline.
+security:
+  - bearerAuth: []
+paths:
+  /api/v1/pipelines/generate:
+    post:
+      tags: [Pipelines]
+      operationId: generatePipeline
+      summary: Сгенерировать pipeline по сообщению пользователя
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PipelineGenerateRequest"
+            examples:
+              travel_offer_case:
+                summary: Travel-offer бизнес-задача
+                value:
+                  dialog_id: "11111111-1111-1111-1111-111111111111"
+                  message: "Сформируй и запусти рассылку тревел-офферов для активных пользователей за последние 7 дней, подбери топ-5 отелей в Берлине, сегментируй пользователей и отправь персональные email по шаблону offer_template_2026."
+                  capability_ids: null
+      responses:
+        "200":
+          description: Pipeline обработан (готов / требует ввод / не может быть собран)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PipelineGenerateResponse"
+              examples:
+                ready:
+                  summary: Линейный pipeline 1 -> 2 -> 3 -> 4 -> 5
+                  value:
+                    status: "ready"
+                    message_ru: "Пайплайн собран. Можно запускать."
+                    chat_reply_ru: "Пайплайн собран: получаем пользователей и отели, сегментируем, назначаем офферы, затем отправляем email."
+                    pipeline_id: "7b17ac70-3f39-4e70-8f8a-4a2f1fd4ff7e"
+                    nodes:
+                      - step: 1
+                        name: "get_recent_users"
+                        description: "Получить активных пользователей за последние 7 дней."
+                        input_connected_from: []
+                        output_connected_to: [3]
+                        input_data_type_from_previous: []
+                        external_inputs: ["days_back"]
+                        endpoints:
+                          - name: "get_recent_users"
+                            capability_id: "c4be1e66-2e04-4c6f-8d8f-6f39f1f46087"
+                            action_id: "e4b0bcb6-6a8c-4b0a-8e18-3f44b5f7d1c2"
+                            output_type: "users[]"
+                      - step: 2
+                        name: "get_top_hotels"
+                        description: "Получить топ-5 отелей в Берлине."
+                        input_connected_from: []
+                        output_connected_to: [3]
+                        input_data_type_from_previous: []
+                        external_inputs: ["city", "hotels_limit"]
+                        endpoints:
+                          - name: "get_top_hotels"
+                            capability_id: "470ae37e-029e-4c67-a293-acb848675d0b"
+                            action_id: "96f0bc8f-e294-46a9-9a0e-48e1b8f2a941"
+                            output_type: "hotels[]"
+                      - step: 3
+                        name: "segment_users_by_hotel_preferences"
+                        description: "Сегментация пользователей по предпочтениям."
+                        input_connected_from: [1, 2]
+                        output_connected_to: [4]
+                        input_data_type_from_previous:
+                          - from_step: 1
+                            type: "users[]"
+                          - from_step: 2
+                            type: "hotels[]"
+                        external_inputs: []
+                        endpoints:
+                          - name: "segment_users_by_hotel_preferences"
+                            capability_id: "518ea04f-f891-4529-8c74-06e8cd9d2f43"
+                            action_id: "92dfce86-34dd-4c1d-9ee7-4214a16cbd99"
+                            output_type: "segments[]"
+                      - step: 4
+                        name: "assign_users_to_hotels"
+                        description: "Назначить пользователю релевантный отель."
+                        input_connected_from: [3]
+                        output_connected_to: [5]
+                        input_data_type_from_previous:
+                          - from_step: 3
+                            type: "segments[]"
+                        external_inputs: []
+                        endpoints:
+                          - name: "assign_users_to_hotels"
+                            capability_id: "70c67642-c8d2-4eb2-a57b-d5e42dc04342"
+                            action_id: "c57f4c88-7307-4e2c-9d36-6756be8e6ab0"
+                            output_type: "assignments[]"
+                      - step: 5
+                        name: "send_hotel_offers_by_email"
+                        description: "Отправить персональные email-офферы."
+                        input_connected_from: [4]
+                        output_connected_to: []
+                        input_data_type_from_previous:
+                          - from_step: 4
+                            type: "assignments[]"
+                        external_inputs: ["template_id"]
+                        endpoints:
+                          - name: "send_hotel_offers_by_email"
+                            capability_id: "3b90595e-3f6f-4b4a-a89a-63daecf8ed03"
+                            action_id: "3c97cc71-5cf6-45fd-8f75-2cf1ccfc7c45"
+                            output_type: "delivery_report"
+                    edges:
+                      - from_step: 1
+                        to_step: 3
+                        type: "data_dependency"
+                      - from_step: 2
+                        to_step: 3
+                        type: "data_dependency"
+                      - from_step: 3
+                        to_step: 4
+                        type: "data_dependency"
+                      - from_step: 4
+                        to_step: 5
+                        type: "data_dependency"
+                    missing_requirements: []
+                    context_summary: "Используются 5 capability для travel-рассылки."
+                needs_input:
+                  summary: Требуется один уточняющий параметр
+                  value:
+                    status: "needs_input"
+                    message_ru: "Уточните template_id для email-рассылки."
+                    chat_reply_ru: "Нужен template_id для шага отправки email. Например: offer_template_2026."
+                    pipeline_id: null
+                    nodes: []
+                    edges: []
+                    missing_requirements: ["template_id"]
+                    context_summary: null
+                cannot_build:
+                  summary: Модель недоступна
+                  value:
+                    status: "cannot_build"
+                    message_ru: "Не удалось обратиться к локальной модели Ollama. Проверьте OLLAMA_HOST/OLLAMA_MODEL и повторите запрос."
+                    chat_reply_ru: "Не удалось обратиться к локальной модели Ollama. Проверьте OLLAMA_HOST/OLLAMA_MODEL и повторите запрос."
+                    pipeline_id: null
+                    nodes: []
+                    edges: []
+                    missing_requirements: ["ollama_unavailable"]
+                    context_summary: null
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "403":
+          $ref: "#/components/responses/ForbiddenError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/pipelines/dialogs:
+    get:
+      tags: [Pipelines]
+      operationId: listPipelineDialogs
+      summary: Получить список диалогов pipeline
+      parameters:
+        - in: query
+          name: limit
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 20
+        - in: query
+          name: offset
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        "200":
+          description: Список диалогов пользователя
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/PipelineDialogListItemResponse"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/pipelines/dialogs/{dialog_id}/history:
+    get:
+      tags: [Pipelines]
+      operationId: getPipelineDialogHistory
+      summary: Получить историю сообщений диалога
+      parameters:
+        - in: path
+          name: dialog_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - in: query
+          name: limit
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 30
+        - in: query
+          name: offset
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        "200":
+          description: История диалога
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PipelineDialogHistoryResponse"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "403":
+          $ref: "#/components/responses/ForbiddenError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/pipelines/dialog/reset:
+    post:
+      tags: [Pipelines]
+      operationId: resetPipelineDialog
+      summary: Сбросить контекст диалога pipeline
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DialogResetRequest"
+      responses:
+        "200":
+          description: Диалог успешно сброшен
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DialogResetResponse"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "403":
+          $ref: "#/components/responses/ForbiddenError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/pipelines/{pipeline_id}/run:
+    post:
+      tags: [Pipelines]
+      operationId: runPipeline
+      summary: Запустить pipeline на выполнение
+      parameters:
+        - in: path
+          name: pipeline_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RunPipelineRequest"
+            examples:
+              travel_inputs:
+                value:
+                  inputs:
+                    days_back: 7
+                    city: "Berlin"
+                    hotels_limit: 5
+                    template_id: "offer_template_2026"
+      responses:
+        "202":
+          description: Запуск поставлен в очередь/начат
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RunPipelineResponse"
+              examples:
+                queued:
+                  value:
+                    run_id: "2fb1f647-b769-4f56-8a44-6a63a364b478"
+                    pipeline_id: "7b17ac70-3f39-4e70-8f8a-4a2f1fd4ff7e"
+                    status: "QUEUED"
+        "400":
+          $ref: "#/components/responses/BadRequestError"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/executions:
+    get:
+      tags: [Executions]
+      operationId: listExecutions
+      summary: Получить список запусков execution
+      parameters:
+        - in: query
+          name: limit
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+        - in: query
+          name: offset
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+      responses:
+        "200":
+          description: Список запусков
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ExecutionRunListItemResponse"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+  /api/v1/executions/{run_id}:
+    get:
+      tags: [Executions]
+      operationId: getExecution
+      summary: Получить детальный отчёт execution run
+      parameters:
+        - in: path
+          name: run_id
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Детали запуска с шагами
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ExecutionRunDetailResponse"
+              examples:
+                partial_failed:
+                  summary: Пример со статусами SUCCEEDED/FAILED/SKIPPED
+                  value:
+                    id: "2fb1f647-b769-4f56-8a44-6a63a364b478"
+                    pipeline_id: "7b17ac70-3f39-4e70-8f8a-4a2f1fd4ff7e"
+                    status: "PARTIAL_FAILED"
+                    inputs:
+                      days_back: 7
+                      city: "Berlin"
+                      hotels_limit: 5
+                      template_id: "offer_template_2026"
+                    summary:
+                      total_steps: 5
+                      succeeded: 3
+                      failed: 1
+                      skipped: 1
+                    error: "Step 4 failed: upstream service timeout"
+                    started_at: "2026-03-16T12:10:15Z"
+                    finished_at: "2026-03-16T12:10:31Z"
+                    created_at: "2026-03-16T12:10:15Z"
+                    updated_at: "2026-03-16T12:10:31Z"
+                    steps:
+                      - step: 1
+                        name: "get_recent_users"
+                        capability_id: "c4be1e66-2e04-4c6f-8d8f-6f39f1f46087"
+                        action_id: "e4b0bcb6-6a8c-4b0a-8e18-3f44b5f7d1c2"
+                        method: "GET"
+                        status_code: 200
+                        status: "SUCCEEDED"
+                        resolved_inputs:
+                          days_back: 7
+                        accepted_payload: null
+                        output_payload:
+                          users: []
+                        request_snapshot:
+                          method: "GET"
+                          path: "/users/recent"
+                        response_snapshot:
+                          status_code: 200
+                          body:
+                            users: []
+                        error: null
+                        started_at: "2026-03-16T12:10:15Z"
+                        finished_at: "2026-03-16T12:10:17Z"
+                        duration_ms: 2100
+                        created_at: "2026-03-16T12:10:15Z"
+                        updated_at: "2026-03-16T12:10:17Z"
+                      - step: 4
+                        name: "assign_users_to_hotels"
+                        capability_id: "70c67642-c8d2-4eb2-a57b-d5e42dc04342"
+                        action_id: "c57f4c88-7307-4e2c-9d36-6756be8e6ab0"
+                        method: "POST"
+                        status_code: 504
+                        status: "FAILED"
+                        resolved_inputs:
+                          segments: []
+                        accepted_payload:
+                          segments: []
+                        output_payload:
+                          detail: "Gateway Timeout"
+                        request_snapshot:
+                          method: "POST"
+                          path: "/assignments/hotels"
+                          json_body:
+                            segments: []
+                        response_snapshot:
+                          status_code: 504
+                          body:
+                            detail: "Gateway Timeout"
+                        error: "Upstream timeout"
+                        started_at: "2026-03-16T12:10:23Z"
+                        finished_at: "2026-03-16T12:10:29Z"
+                        duration_ms: 6010
+                        created_at: "2026-03-16T12:10:23Z"
+                        updated_at: "2026-03-16T12:10:29Z"
+                      - step: 5
+                        name: "send_hotel_offers_by_email"
+                        capability_id: "3b90595e-3f6f-4b4a-a89a-63daecf8ed03"
+                        action_id: "3c97cc71-5cf6-45fd-8f75-2cf1ccfc7c45"
+                        method: null
+                        status_code: null
+                        status: "SKIPPED"
+                        resolved_inputs: null
+                        accepted_payload: null
+                        output_payload: null
+                        request_snapshot: null
+                        response_snapshot: null
+                        error: "Skipped: run stopped after failure at step 4"
+                        started_at: null
+                        finished_at: null
+                        duration_ms: null
+                        created_at: "2026-03-16T12:10:29Z"
+                        updated_at: "2026-03-16T12:10:29Z"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          $ref: "#/components/responses/NotFoundError"
+        "422":
+          $ref: "#/components/responses/ValidationError"
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+  responses:
+    BadRequestError:
+      description: Некорректный запрос
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          examples:
+            not_ready:
+              value:
+                detail: "Pipeline is not ready for execution"
+    UnauthorizedError:
+      description: Не передан или некорректен JWT токен
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          examples:
+            invalid_credentials:
+              value:
+                detail: "Could not validate credentials"
+    ForbiddenError:
+      description: Нет доступа к ресурсу диалога
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          examples:
+            dialog_denied:
+              value:
+                detail: "Access denied for dialog"
+    NotFoundError:
+      description: Сущность не найдена
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorResponse"
+          examples:
+            not_found:
+              value:
+                detail: "Pipeline not found"
+    ValidationError:
+      description: Ошибка валидации входных данных
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/HTTPValidationError"
+
+  schemas:
+    ErrorResponse:
+      type: object
+      properties:
+        detail:
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+            - type: array
+              items:
+                type: object
+                additionalProperties: true
+
+    ValidationError:
+      type: object
+      required: [loc, msg, type]
+      properties:
+        loc:
+          type: array
+          items:
+            oneOf:
+              - type: string
+              - type: integer
+        msg:
+          type: string
+        type:
+          type: string
+
+    HTTPValidationError:
+      type: object
+      properties:
+        detail:
+          type: array
+          items:
+            $ref: "#/components/schemas/ValidationError"
+
+    PipelineInputTypeFromPrevious:
+      type: object
+      required: [from_step, type]
+      properties:
+        from_step:
+          type: integer
+        type:
+          type: string
+
+    PipelineStepEndpoint:
+      type: object
+      required: [name, capability_id]
+      properties:
+        name:
+          type: string
+        capability_id:
+          type: string
+          format: uuid
+        action_id:
+          type: string
+          format: uuid
+          nullable: true
+        type:
+          type: string
+          nullable: true
+        input_type:
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+          nullable: true
+        output_type:
+          oneOf:
+            - type: string
+            - type: object
+              additionalProperties: true
+          nullable: true
+
+    PipelineGraphNode:
+      type: object
+      required: [step, name]
+      properties:
+        step:
+          type: integer
+        name:
+          type: string
+        description:
+          type: string
+          nullable: true
+        input_connected_from:
+          type: array
+          items:
+            type: integer
+          default: []
+        output_connected_to:
+          type: array
+          items:
+            type: integer
+          default: []
+        input_data_type_from_previous:
+          type: array
+          items:
+            $ref: "#/components/schemas/PipelineInputTypeFromPrevious"
+          default: []
+        external_inputs:
+          type: array
+          items:
+            type: string
+          default: []
+        endpoints:
+          type: array
+          items:
+            $ref: "#/components/schemas/PipelineStepEndpoint"
+          default: []
+
+    PipelineGraphEdge:
+      type: object
+      required: [from_step, to_step, type]
+      properties:
+        from_step:
+          type: integer
+        to_step:
+          type: integer
+        type:
+          type: string
+
+    PipelineGenerateRequest:
+      type: object
+      required: [dialog_id, message]
+      properties:
+        dialog_id:
+          type: string
+          format: uuid
+        message:
+          type: string
+          minLength: 1
+        capability_ids:
+          type: array
+          items:
+            type: string
+            format: uuid
+          nullable: true
+
+    PipelineGenerateResponse:
+      type: object
+      required: [status, message_ru, chat_reply_ru, nodes, edges, missing_requirements]
+      properties:
+        status:
+          type: string
+          enum: [ready, needs_input, cannot_build]
+        message_ru:
+          type: string
+        chat_reply_ru:
+          type: string
+        pipeline_id:
+          type: string
+          format: uuid
+          nullable: true
+        nodes:
+          type: array
+          items:
+            $ref: "#/components/schemas/PipelineGraphNode"
+          default: []
+        edges:
+          type: array
+          items:
+            $ref: "#/components/schemas/PipelineGraphEdge"
+          default: []
+        missing_requirements:
+          type: array
+          items:
+            type: string
+          default: []
+        context_summary:
+          type: string
+          nullable: true
+
+    DialogResetRequest:
+      type: object
+      required: [dialog_id]
+      properties:
+        dialog_id:
+          type: string
+          format: uuid
+
+    DialogResetResponse:
+      type: object
+      required: [status, message_ru]
+      properties:
+        status:
+          type: string
+          enum: [ok]
+        message_ru:
+          type: string
+
+    PipelineDialogListItemResponse:
+      type: object
+      required: [dialog_id, created_at, updated_at]
+      properties:
+        dialog_id:
+          type: string
+          format: uuid
+        title:
+          type: string
+          nullable: true
+        last_status:
+          type: string
+          nullable: true
+        last_pipeline_id:
+          type: string
+          format: uuid
+          nullable: true
+        last_message_preview:
+          type: string
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    PipelineDialogMessageResponse:
+      type: object
+      required: [id, role, content, created_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        role:
+          type: string
+          enum: [user, assistant]
+        content:
+          type: string
+        assistant_payload:
+          type: object
+          additionalProperties: true
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    PipelineDialogHistoryResponse:
+      type: object
+      required: [dialog_id, messages]
+      properties:
+        dialog_id:
+          type: string
+          format: uuid
+        title:
+          type: string
+          nullable: true
+        messages:
+          type: array
+          items:
+            $ref: "#/components/schemas/PipelineDialogMessageResponse"
+          default: []
+
+    RunPipelineRequest:
+      type: object
+      properties:
+        inputs:
+          type: object
+          additionalProperties: true
+          default: {}
+
+    RunPipelineResponse:
+      type: object
+      required: [run_id, pipeline_id, status]
+      properties:
+        run_id:
+          type: string
+          format: uuid
+        pipeline_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [QUEUED, RUNNING]
+
+    ExecutionRunListItemResponse:
+      type: object
+      required: [id, pipeline_id, status, created_at, updated_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        pipeline_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [QUEUED, RUNNING, SUCCEEDED, FAILED, PARTIAL_FAILED]
+        error:
+          type: string
+          nullable: true
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        finished_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    ExecutionStepRunResponse:
+      type: object
+      required: [step, status, accepted_payload, output_payload, created_at, updated_at]
+      properties:
+        step:
+          type: integer
+        name:
+          type: string
+          nullable: true
+        capability_id:
+          type: string
+          format: uuid
+          nullable: true
+        action_id:
+          type: string
+          format: uuid
+          nullable: true
+        method:
+          type: string
+          enum: [GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS]
+          nullable: true
+        status_code:
+          type: integer
+          nullable: true
+        status:
+          type: string
+          enum: [PENDING, RUNNING, SUCCEEDED, FAILED, SKIPPED]
+        resolved_inputs:
+          type: object
+          additionalProperties: true
+          nullable: true
+        accepted_payload:
+          nullable: true
+        output_payload:
+          nullable: true
+        request_snapshot:
+          type: object
+          additionalProperties: true
+          nullable: true
+        response_snapshot:
+          type: object
+          additionalProperties: true
+          nullable: true
+        error:
+          type: string
+          nullable: true
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        finished_at:
+          type: string
+          format: date-time
+          nullable: true
+        duration_ms:
+          type: integer
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    ExecutionRunDetailResponse:
+      type: object
+      required: [id, pipeline_id, status, inputs, created_at, updated_at, steps]
+      properties:
+        id:
+          type: string
+          format: uuid
+        pipeline_id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [QUEUED, RUNNING, SUCCEEDED, FAILED, PARTIAL_FAILED]
+        inputs:
+          type: object
+          additionalProperties: true
+          default: {}
+        summary:
+          type: object
+          additionalProperties: true
+          nullable: true
+        error:
+          type: string
+          nullable: true
+        started_at:
+          type: string
+          format: date-time
+          nullable: true
+        finished_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        steps:
+          type: array
+          items:
+            $ref: "#/components/schemas/ExecutionStepRunResponse"
+          default: []