66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# 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 архитектура.
|
|
|