core/engine/src/api/__init__.py - main - alexefan136/flowstack

core/engine/src/api/__init__.py
347 строк10 KB
Alexander Efanov
upd fix
04 авг 2026, 14:09
04 авг 2026, 14:09f63ab86
"""API package — FastAPI endpoints для FlowStack Engine.

Предоставляет полный REST API для управления:
- **Chats** — диалоги с LLM, streaming ответов, RAG интеграция
- **Agents** — AI агенты (AgentRuntime: LLM loop + function calling)
- **Skills** — переиспользуемые промпт-шаблоны (render → LLM)
- **Tasks** — пользовательские задачи с приоритетами и runs
- **Flows** — мульти-агентные workflow (графы nodes/edges, DB-based)
- **Runs** — predefined multi-agent flows (FLOW_REGISTRY, string IDs)
- **MCP Servers** — Model Context Protocol серверы (lifecycle + tools)
- **Tools** — Tool Registry + MCP JSON-RPC endpoint (spec 2024-11-05)

Architecture:
- Все endpoints следуют RESTful конвенциям
- Automatic multi-tenancy изоляция через UserContext
- SSE streaming для LLM/agent/flow ответов
- Full MCP 2024-11-05 compliance (tools, resources, prompts)

Usage в main.py:
    from src.api import register_all_routers

    app = FastAPI(...)
    register_all_routers(app)

Или вручную:
    from src.api import chats_router, agents_router, flows_router, ...
    app.include_router(chats_router)
"""

from __future__ import annotations

from typing import Any

from fastapi import FastAPI

# ============================================================================
# ROUTER IMPORTS
# ============================================================================
from .agents import router as agents_router
from .chats import router as chats_router

# ============================================================================
# DEPENDENCIES RE-EXPORT (для convenience)
# ============================================================================
from .dependencies import (
    # Repositories
    get_agent_repo,
    # Services
    get_agent_service,
    get_chat_memory_repo,
    get_chat_repo,
    get_chat_service,
    # Core
    get_db_session,
    get_flow_repo,
    get_flow_service,
    # Runtime
    get_mcp_manager_dep,
    get_mcp_server_repo,
    get_mcp_service,
    get_message_repo,
    get_skill_repo,
    get_skill_service,
    get_task_repo,
    get_task_service,
    get_user_ctx,
    # Utilities
    get_user_id,
    get_user_repo,
    get_workspace_id,
)
from .flows import router as flows_router
from .mcp_servers import router as mcp_servers_router
from .runs import router as runs_router
from .skills import router as skills_router
from .tasks import router as tasks_router
from .tools import router as tools_router

# ============================================================================
# API METADATA
# ============================================================================


API_VERSION = "1.0.0"
API_PREFIX = "/api/v1"

# Теги для OpenAPI документации
API_TAGS: list[dict[str, str]] = [
    {
        "name": "chats",
        "description": (
            "Чаты с LLM. Поддержка streaming (SSE), RAG интеграции, экспорта и поиска по истории."
        ),
    },
    {
        "name": "agents",
        "description": (
            "AI агенты (AgentRuntime: LLM loop + function calling). "
            "Поддержка streaming выполнения и statistics tracking."
        ),
    },
    {
        "name": "skills",
        "description": (
            "Переиспользуемые промпт-шаблоны. Публичные/приватные скиллы "
            "с категориями, параметрами, запуском (render → LLM) и usage tracking."
        ),
    },
    {
        "name": "tasks",
        "description": (
            "Пользовательские задачи с приоритетами, статусами, deadline, "
            "recurrence patterns и историей выполнений (runs)."
        ),
    },
    {
        "name": "flows",
        "description": (
            "Orchestration flows — мульти-агентные workflow (графы nodes/edges). "
            "DB-based с UUID, валидация графа, безопасные conditions, запуск с streaming."
        ),
    },
    {
        "name": "runs",
        "description": (
            "Predefined multi-agent flows (research, brainstorm, debate, code_review, "
            "consensus, compare, analyze). Идентифицируются строковым ID, "
            "исполняются через FLOW_REGISTRY."
        ),
    },
    {
        "name": "mcp-servers",
        "description": (
            "Model Context Protocol серверы (GitHub, GitLab, PostgreSQL, etc.). "
            "Lifecycle management (start/stop/restart), discovery и вызов tools."
        ),
    },
    {
        "name": "tools",
        "description": (
            "Tool Registry доступ + MCP JSON-RPC 2.0 endpoint. "
            "Соответствует MCP specification 2024-11-05."
        ),
    },
    {
        "name": "system",
        "description": "Системные endpoints: health check, ready check, system info.",
    },
]


# ============================================================================
# ROUTER REGISTRY
# ============================================================================


# Список всех API роутеров с metadata
ROUTERS: list[dict[str, Any]] = [
    {
        "router": chats_router,
        "name": "chats",
        "prefix": f"{API_PREFIX}/chats",
        "description": "Чаты и сообщения",
    },
    {
        "router": agents_router,
        "name": "agents",
        "prefix": f"{API_PREFIX}/agents",
        "description": "AI агенты",
    },
    {
        "router": skills_router,
        "name": "skills",
        "prefix": f"{API_PREFIX}/skills",
        "description": "Промпт-шаблоны",
    },
    {
        "router": tasks_router,
        "name": "tasks",
        "prefix": f"{API_PREFIX}/tasks",
        "description": "Пользовательские задачи",
    },
    {
        "router": flows_router,
        "name": "flows",
        "prefix": f"{API_PREFIX}/flows",
        "description": "Orchestration flows (DB-based, UUID)",
    },
    {
        "router": runs_router,
        "name": "runs",
        "prefix": f"{API_PREFIX}/runs",
        "description": "Predefined multi-agent flows (FLOW_REGISTRY)",
    },
    {
        "router": mcp_servers_router,
        "name": "mcp_servers",
        "prefix": f"{API_PREFIX}/mcp-servers",
        "description": "MCP серверы",
    },
    {
        "router": tools_router,
        "name": "tools",
        "prefix": f"{API_PREFIX}/tools",
        "description": "Tool Registry + MCP endpoint",
    },
]


# ============================================================================
# HELPER FUNCTIONS
# ============================================================================


def register_all_routers(app: FastAPI) -> None:
    """
    Зарегистрировать все API роутеры в FastAPI приложении.

    Автоматически добавляет все модули из src.api.* с правильными
    prefixes и tags.

    Usage:
        ```python
        from fastapi import FastAPI
        from src.api import register_all_routers

        app = FastAPI(
            title="FlowStack Engine",
            openapi_tags=API_TAGS,
        )
        register_all_routers(app)
        ```
    """
    for router_info in ROUTERS:
        app.include_router(router_info["router"])


def get_api_info() -> dict[str, Any]:
    """
    Получить информацию о всех доступных API endpoints.

    Используется для системного endpoint /info или документации.

    Returns:
        Dict с описанием всех API модулей и их endpoints.
    """
    modules: list[dict[str, Any]] = []

    for router_info in ROUTERS:
        router = router_info["router"]
        routes = []

        for route in router.routes:
            if hasattr(route, "methods") and hasattr(route, "path"):
                routes.append(
                    {
                        "path": route.path,
                        "methods": list(route.methods) if route.methods else [],
                        "name": getattr(route, "name", None),
                        "summary": getattr(route, "summary", None),
                    }
                )

        modules.append(
            {
                "name": router_info["name"],
                "prefix": router_info["prefix"],
                "description": router_info["description"],
                "routes_count": len(routes),
                "routes": routes,
            }
        )

    return {
        "api_version": API_VERSION,
        "api_prefix": API_PREFIX,
        "modules": modules,
        "total_modules": len(modules),
        "total_routes": sum(m["routes_count"] for m in modules),
    }


def get_openapi_tags() -> list[dict[str, str]]:
    """
    Получить список тегов для OpenAPI документации.

    Usage:
        ```python
        app = FastAPI(
            title="FlowStack Engine",
            openapi_tags=get_openapi_tags(),
        )
        ```
    """
    return API_TAGS.copy()


# ============================================================================
# EXPORTS
# ============================================================================


__all__ = [  # noqa: RUF022
    # Routers
    "chats_router",
    "agents_router",
    "skills_router",
    "tasks_router",
    "flows_router",
    "runs_router",
    "mcp_servers_router",
    "tools_router",
    # Dependencies (core)
    "get_db_session",
    "get_user_ctx",
    # Dependencies (repositories)
    "get_user_repo",
    "get_chat_repo",
    "get_message_repo",
    "get_chat_memory_repo",
    "get_skill_repo",
    "get_agent_repo",
    "get_task_repo",
    "get_flow_repo",
    "get_mcp_server_repo",
    # Dependencies (services)
    "get_chat_service",
    "get_agent_service",
    "get_flow_service",
    "get_skill_service",
    "get_task_service",
    "get_mcp_service",
    # Dependencies (runtime)
    "get_mcp_manager_dep",
    # Dependencies (utilities)
    "get_workspace_id",
    "get_user_id",
    # Helpers
    "register_all_routers",
    "get_api_info",
    "get_openapi_tags",
    # Metadata
    "API_VERSION",
    "API_PREFIX",
    "API_TAGS",
    "ROUTERS",
]