COMPUTE_PLANE_ARCHITECTURE.md

# =====================================================
# Apckeyl Framework
# COMPUTE PLANE ARCHITECTURE
# Version 1.0
# =====================================================

# 1. Purpose

Compute Plane — это слой Apckeyl Framework,
который отвечает за выполнение реальных вычислительных
задач через внешние Compute Modules.

Orchestrator не должен выполнять тяжёлые вычисления
сам.

Orchestrator управляет задачей.

Compute Module выполняет задачу.

Основной принцип:

    Control Plane
          ↓
    Compute Plane
          ↓
    External Compute Module


# 2. Architectural Principle

Apckeyl Orchestrator является Control Center.

Он не должен быть привязан к конкретному
вычислительному серверу.

Compute Module может находиться:

- в отдельном Hugging Face Space;
- на другом бесплатном сервисе;
- на GPU-сервисе;
- на CPU-сервисе;
- в локальном окружении;
- на собственном сервере;
- на другом совместимом API.

Control Plane не должен зависеть от конкретного
места размещения Compute Module.


# 3. Current Compute Module

Первым реальным Compute Module является:

    Apckeyl_RealESRGAN


Назначение:

    Image Upscaling


Тип:

    image_upscaler


Основной capability:

    image_upscale


Текущий Space:

    Apckeyl_RealESRGAN


Этот Space сохраняется отдельно.

Orchestrator не заменяет Apckeyl_RealESRGAN.

Orchestrator управляет доступом к нему.


# 4. Separation of Responsibilities

## Control Plane

Control Plane отвечает за:

- создание задач;
- идентификацию задач;
- выбор модуля;
- маршрутизацию;
- управление статусами;
- управление очередью;
- регистрацию Compute Modules;
- мониторинг;
- логирование;
- обработку ошибок;
- получение результатов.


## Compute Plane

Compute Plane отвечает за:

- выполнение конкретной вычислительной операции;
- обработку входных данных;
- запуск модели;
- сохранение результата;
- возврат результата Orchestrator.


## Compute Module

Compute Module является независимым исполнителем.

Например:

    Apckeyl_RealESRGAN

получает задачу:

    image_upscale

выполняет upscale

и возвращает результат.


# 5. Communication Model

На первом этапе используется HTTP/API-модель.

Общий поток:

    User
      ↓
    Client
      ↓
    Orchestrator
      ↓
    Control Plane
      ↓
    Task Manager
      ↓
    Module Registry
      ↓
    Compute Module
      ↓
    Result
      ↓
    Orchestrator
      ↓
    User


# 6. Important Rule

Control Plane не должен знать внутреннюю реализацию
Compute Module.

Например:

Orchestrator не должен знать:

- какую AI-модель использует RealESRGAN;
- какие Python-библиотеки установлены;
- какой код находится внутри Space;
- какой GPU или CPU используется;
- каким образом происходит обработка изображения.


Orchestrator знает только контракт.

Например:

    module_id
    module_type
    capabilities
    endpoint
    status


# 7. Compute Module Contract

Каждый Compute Module должен иметь стандартное
описание.

Минимальный контракт:

    module_id
    module_name
    module_type
    capabilities
    endpoint
    status


Пример:

    module_id:
        realesrgan

    module_name:
        Apckeyl_RealESRGAN

    module_type:
        image_upscaler

    capabilities:
        image_upscale

    status:
        available


# 8. Task Contract

Control Plane создаёт задачу.

Минимальная структура:

    task_id
    task_type
    status
    module_id
    payload
    created_at


Пример:

    task_id:
        task_000001

    task_type:
        image_upscale

    status:
        created

    module_id:
        realesrgan


# 9. Task Lifecycle

Основной жизненный цикл:

    created
       ↓
    queued
       ↓
    dispatched
       ↓
    processing
       ↓
    completed


При ошибке:

    processing
       ↓
    failed


При отмене:

    created
       ↓
    cancelled


# 10. Dispatch

Dispatch — передача задачи выбранному
Compute Module.

Например:

    image_upscale
          ↓
    Control Plane
          ↓
    realesrgan
          ↓
    Apckeyl_RealESRGAN


Dispatch не должен быть связан
с конкретной реализацией модели.


# 11. Endpoint Abstraction

Compute Module должен рассматриваться
как внешний endpoint.

Control Plane не должен зависеть
от конкретного транспорта.

На первом этапе:

    HTTP


В будущем возможно:

    REST API
    Webhook
    Queue
    Internal API
    RPC
    другие совместимые механизмы


# 12. Availability

Каждый Compute Module должен иметь статус.

Минимальные состояния:

    available
    unavailable
    busy
    error
    disabled


Control Plane не должен отправлять задачу
в модуль со статусом:

    unavailable

или:

    disabled


# 13. Health Check

В будущем Orchestrator должен периодически
проверять Compute Modules.

Health Check должен определять:

- доступность endpoint;
- время ответа;
- корректность ответа;
- состояние модуля.


Пример:

    available
        ↓
    health check
        ↓
    response OK
        ↓
    available


При ошибке:

    available
        ↓
    health check
        ↓
    error
        ↓
    unavailable


# 14. Timeout

Каждый внешний Compute Module должен иметь
ограничение времени ожидания.

Если Compute Module не отвечает
в установленный период:

    timeout


Control Plane не должен зависать бесконечно.


# 15. Retry

При временной ошибке возможен повторный запрос.

Пример:

    dispatch
       ↓
    timeout
       ↓
    retry #1
       ↓
    timeout
       ↓
    retry #2
       ↓
    failed


Количество повторов должно быть ограничено.


# 16. Result Handling

Compute Module возвращает результат.

Результат должен быть связан
с исходным task_id.

Пример:

    task_id:
        task_000001

    status:
        completed

    result:
        output_file


Orchestrator принимает результат
и передаёт его следующему слою.


# 17. File Handling

Большие файлы не должны передаваться
через Control Plane без необходимости.

В будущем предпочтительная схема:

    User
      ↓
    upload
      ↓
    temporary storage
      ↓
    task
      ↓
    Compute Module
      ↓
    result storage
      ↓
    User


Это позволит уменьшить нагрузку
на Orchestrator.


# 18. Resource Independence

Compute Module может использовать:

    CPU
    GPU
    ZeroGPU
    другой вычислительный ресурс


Orchestrator не должен предполагать,
какой именно ресурс используется.

Например:

    Orchestrator
          ↓
    Apckeyl_RealESRGAN
          ↓
    CPU Basic


или:

    Orchestrator
          ↓
    другой Compute Module
          ↓
    GPU


Архитектура должна поддерживать оба варианта.


# 19. ZeroGPU Rule

Orchestrator не должен использовать ZeroGPU
как обязательный вычислительный ресурс.

ZeroGPU рассматривается только как возможная
инфраструктурная среда для конкретного модуля.

Это означает:

    ZeroGPU ≠ Orchestrator architecture


Orchestrator должен продолжать работать
как Control Plane независимо от наличия ZeroGPU.


# 20. Free Infrastructure Strategy

Apckeyl Framework проектируется с приоритетом
бесплатной инфраструктуры.

При выборе Compute Modules необходимо
предпочитать:

- бесплатные сервисы;
- бесплатные Hugging Face Spaces;
- бесплатные CPU/GPU ресурсы;
- бесплатные API;
- локальные ресурсы только при необходимости.


Платные сервисы не являются обязательной
частью архитектуры.


# 21. Commercial Use

Для каждого AI Compute Module необходимо
проверять лицензию используемой модели.

До подключения модели необходимо определить:

- model name;
- version;
- license;
- commercial use allowed;
- YouTube allowed;
- sale allowed.


Эта информация должна фиксироваться
в документации проекта.


# 22. Compute Module Independence

Каждый Compute Module должен быть заменяемым.

Например:

    Apckeyl_RealESRGAN
           ↓
       заменить
           ↓
    другой Image Upscaler


Control Plane не должен требовать
переписывания архитектуры.


# 23. Module Selection

Выбор Compute Module производится
через Module Registry.

Пример:

    task_type:
        image_upscale

          ↓

    module_type:
        image_upscaler

          ↓

    capability:
        image_upscale

          ↓

    selected module:
        realesrgan


# 24. Multiple Modules

В будущем один capability может иметь
несколько Compute Modules.

Например:

    image_upscale

        ├── realesrgan
        ├── upscaler_2
        └── upscaler_3


Control Plane сможет выбирать
доступный модуль.


# 25. Fallback

Если основной Compute Module недоступен:

    realesrgan
        ↓
    unavailable

Control Plane может выбрать
другой совместимый модуль:

    upscaler_2


Fallback является будущей функцией.


# 26. Priority

Compute Modules в будущем могут иметь
приоритет.

Например:

    realesrgan
        priority: 100

    upscaler_2
        priority: 50


Control Plane выбирает модуль
с учётом:

- availability;
- priority;
- health;
- capability;
- нагрузки.


# 27. Queue

Если Compute Module занят,
задача не должна теряться.

Она должна перейти:

    created
       ↓
    queued


После освобождения модуля:

    queued
       ↓
    dispatched


# 28. Concurrency

Каждый Compute Module может иметь
ограничение одновременных задач.

Например:

    max_concurrent_tasks:
        1


или:

    max_concurrent_tasks:
        2


Control Plane должен учитывать это
при dispatch.


# 29. Error Isolation

Ошибка Compute Module
не должна ломать Control Plane.

Например:

    Apckeyl_RealESRGAN
           ↓
         ERROR


Orchestrator продолжает работать.

Статус модуля:

    error


Задача:

    failed


Control Plane:

    running


# 30. Security

Endpoint Compute Module не должен
считаться доверенным автоматически.

В будущем необходимо поддерживать:

- authentication;
- authorization;
- tokens;
- signed requests;
- HTTPS;
- ограничение доступа.


Секреты не должны храниться
в исходном коде.


# 31. Logging

Каждый dispatch должен логироваться.

Минимально:

    task_id
    module_id
    timestamp
    status
    duration
    error


Пример:

    task_000001
    realesrgan
    dispatched
    processing
    completed


# 32. Monitoring

Resource Monitor в будущем должен
контролировать:

- количество задач;
- очередь;
- время обработки;
- ошибки;
- доступность модулей;
- latency;
- нагрузку.


# 33. Architecture Diagram

Общая схема:

    ┌───────────────────────────────┐
    │            USER               │
    └───────────────┬───────────────┘
                    │
                    ▼
    ┌───────────────────────────────┐
    │         ORCHESTRATOR          │
    │                               │
    │         CONTROL PLANE         │
    │                               │
    │  Task Manager                 │
    │  Module Registry              │
    │  Dispatcher                   │
    │  Queue                        │
    │  Logger                       │
    │  Resource Monitor             │
    └───────────────┬───────────────┘
                    │
                    ▼
    ┌───────────────────────────────┐
    │         COMPUTE PLANE         │
    └───────────────┬───────────────┘
                    │
          ┌─────────┼─────────┐
          │         │         │
          ▼         ▼         ▼
    RealESRGAN   Image AI   Video AI
       Space       Space       Space


# 34. Current Architecture

На текущем этапе реализованы:

    Module Registry
    Control Plane
    Task Manager
    Control Plane Tests
    Diagnostic Report


Следующий этап:

    Dispatcher


После Dispatcher:

    Compute Module Adapter


После Adapter:

    Apckeyl_RealESRGAN connection


# 35. First Real Integration

Первым реальным внешним Compute Module
остаётся:

    Apckeyl_RealESRGAN


Интеграция должна выполняться
через отдельный adapter.

Control Plane не должен содержать
специфичный код RealESRGAN.


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

    Control Plane
          ↓
    Compute Adapter
          ↓
    Apckeyl_RealESRGAN


# 36. Future Compute Modules

Архитектура должна позволять подключать:

    Image Generation
    Video Generation
    Story Character Studio
    Image Upscaler
    Video Upscaler
    Stock Factory
    другие AI-модули


Каждый модуль должен подключаться
через единый контракт.


# 37. Final Principle

Apckeyl Orchestrator не является
одним большим AI-приложением.

Он является системой управления
независимыми Compute Modules.

Основная идея:

    ORCHESTRATE
        NOT
    COMPUTE


Control Plane управляет.

Compute Plane выполняет.

Compute Modules остаются независимыми.

# =====================================================
# End of COMPUTE_PLANE_ARCHITECTURE.md
# Version 1.0
# =====================================================