ai_orchestrator/docs/adr/001-runtime-stack.md

ADR 001: Runtime Stack

Status

Accepted

Context

AI Orchestrator должен быть:

• независимым от Local LLM Platform;
• пригодным для долгоживущих task runtime;
• удобным для строгой типизации контрактов;
• удобным для async I/O: models, MCP, worker connections, event streams;
• запускаемым без Docker на локальной машине;
• переносимым на удаленное окружение, включая docker-test.

Decision

Основной стек:

• язык: Python 3.13+;
• HTTP API: FastAPI;
• конфиги и схемы запроса/ответа: Pydantic v2;
• app settings: pydantic-settings;
• конфиги проекта: YAML;
• event streaming для UI: SSE как основной transport;
• worker transport: WebSocket;
• structured logging: JSON lines через стандартный logging layer и event envelopes;
• тесты: pytest + pytest-asyncio;
• runtime packaging: стандартный pyproject.toml.

Why This Stack

Python хорошо подходит для orchestration-heavy систем, где важнее:

• строгое моделирование состояния;
• быстрая интеграция с внешними AI/MCP endpoint;
• асинхронный I/O;
• прозрачные схемы данных;
• простая локальная разработка без контейнеров.

FastAPI выбран как delivery adapter, а не как центр архитектуры. Доменные модели и application services не должны зависеть от FastAPI.

Consequences

Плюсы:

• быстрый путь к строгим контрактам;
• хорошая ergonomics для async adapters;
• удобный локальный запуск без Docker;
• понятный переход к PostgreSQL и production deployment.

Минусы:

• нужен дисциплинированный layering, чтобы не “утонуть” в framework-driven code;
• CPU-heavy задачи должны оставаться вне основного request loop.

Non-Goals

• локальный Docker как обязательный dev path;
• тяжелая зависимость от конкретной ORM на уровне domain;
• framework-first архитектура.