COMPUTE_MODULE_CONTRACT.md

# =====================================================
# Apckeyl Framework
# COMPUTE MODULE CONTRACT
# Version 1.0
# =====================================================

# 1. Назначение

Compute Module — это внешний или локальный вычислительный
модуль Apckeyl Framework, который непосредственно выполняет
тяжёлую вычислительную задачу.

Compute Module не является частью Control Plane.

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

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

---

# 2. Архитектурная схема

Control Plane
      ↓
Task Manager
      ↓
Dispatcher
      ↓
Compute Adapter
      ↓
Compute Module
      ↓
Result
      ↓
Compute Adapter
      ↓
Control Plane

---

# 3. Основной принцип

Compute Module должен быть максимально независимым
от внутренней реализации Apckeyl Control Plane.

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

- Compute Module не управляет очередью;
- Compute Module не выбирает задачи;
- Compute Module не управляет другими модулями;
- Compute Module не принимает архитектурные решения;
- Compute Module не должен знать внутреннюю структуру
  Control Plane.

Его основная задача:

INPUT → COMPUTE → OUTPUT

---

# 4. Минимальный контракт

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

1. module_id
2. module_name
3. module_version
4. supported_tasks
5. input_contract
6. output_contract
7. health information
8. execution interface

---

# 5. Module Identity

Каждый модуль должен иметь уникальный идентификатор.

Пример:

module_id:

    realesrgan

Название:

    Apckeyl_RealESRGAN

Версия:

    1.0

---

# 6. Supported Tasks

Compute Module должен явно сообщать,
какие типы задач он поддерживает.

Пример:

supported_tasks:

    image_upscale

В будущем:

    image_generation
    image_restoration
    face_restoration
    video_upscale
    video_processing

Модуль не должен принимать задачу,
которую он официально не поддерживает.

---

# 7. Input Contract

Dispatcher передаёт Compute Adapter задачу
в стандартизированном формате.

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

{
    "task_id": "...",
    "task_type": "...",
    "payload": {...}
}

---

# 8. task_id

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

Пример:

task_000001

Compute Module должен сохранять этот идентификатор
в результате выполнения.

Это позволяет Control Plane сопоставить:

task → execution → result

---

# 9. task_type

task_type определяет тип вычислительной операции.

Пример:

image_upscale

Compute Module должен проверять,
поддерживает ли он полученный task_type.

---

# 10. Payload

payload содержит параметры конкретной операции.

Для image_upscale пример:

{
    "filename": "image.png",
    "scale": 4
}

Конкретная структура payload зависит
от конкретного Compute Module.

---

# 11. Output Contract

После выполнения Compute Module должен вернуть
стандартизированный результат.

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

{
    "task_id": "...",
    "status": "...",
    "result": {...}
}

---

# 12. Статусы выполнения

Минимально поддерживаются:

prepared

running

completed

failed

---

# 13. prepared

Статус prepared означает:

задача принята адаптером и подготовлена
для передачи Compute Module.

Это ещё не означает,
что вычисление началось.

---

# 14. running

Статус running означает:

Compute Module начал выполнение задачи.

---

# 15. completed

Статус completed означает:

вычисление завершено успешно.

Результат должен находиться
в поле result.

---

# 16. failed

Статус failed означает:

Compute Module не смог выполнить задачу.

При ошибке должен быть доступен
информационный блок error.

Пример:

{
    "task_id": "task_000001",
    "status": "failed",
    "error": "Processing failed"
}

---

# 17. Health Check

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

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

{
    "module_id": "...",
    "status": "healthy"
}

Возможные состояния:

healthy

unavailable

degraded

unknown

---

# 18. Compute Adapter

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

Для этого используется Compute Adapter.

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

Control Plane
      ↓
Dispatcher
      ↓
Compute Adapter
      ↓
Compute Module

---

# 19. Ответственность Adapter

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

- подготовку запроса;
- преобразование формата;
- передачу задачи;
- получение результата;
- преобразование результата
  в формат Apckeyl Framework.

---

# 20. Ответственность Compute Module

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

- получение задачи;
- проверку входных данных;
- выполнение вычисления;
- формирование результата;
- сообщение об ошибке;
- сообщение о состоянии.

---

# 21. Что Compute Module НЕ должен делать

Compute Module не должен:

- создавать глобальную очередь Apckeyl;
- управлять Task Manager;
- изменять Module Registry;
- самостоятельно выбирать другой Compute Module;
- управлять Control Plane;
- хранить секреты Control Plane;
- принимать архитектурные решения Framework.

---

# 22. Независимость модулей

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

Например:

Control Plane
      ↓
Dispatcher
      ↓
Compute Adapter
      ↓
Apckeyl_RealESRGAN

может быть заменён на:

Control Plane
      ↓
Dispatcher
      ↓
Compute Adapter
      ↓
Другой Upscaler

без изменения основной архитектуры Control Plane.

---

# 23. Первый Compute Module

Первым реальным Compute Module
Apckeyl Framework будет:

Apckeyl_RealESRGAN

Назначение:

AI image upscaling.

Основная задача:

image_upscale

---

# 24. Apckeyl_RealESRGAN

Apckeyl_RealESRGAN должен оставаться
самостоятельным Space.

Он не должен становиться частью
Control Plane.

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

Apckeyl Framework
        ↓
Compute Adapter
        ↓
Apckeyl_RealESRGAN
        ↓
Real-ESRGAN
        ↓
Processed Image

---

# 25. Separation of Concerns

Framework отвечает за:

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

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

- вычисление.

---

# 26. Ошибки

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

Framework errors:

- invalid task;
- unknown module;
- invalid routing;
- invalid request.

Compute errors:

- invalid input;
- processing failure;
- model failure;
- resource failure;
- external service failure.

---

# 27. Security

Compute Module не должен получать
лишние секреты.

API keys и другие credentials
должны передаваться только тогда,
когда они действительно необходимы
для выполнения конкретной операции.

Секреты не должны:

- записываться в обычные логи;
- возвращаться пользователю;
- храниться внутри task payload;
- публиковаться в Git repository.

---

# 28. Commercial Use

При выборе моделей и сервисов
для Compute Module необходимо
проверять лицензию.

Для каждого AI-модуля желательно фиксировать:

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

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

---

# 29. Free Infrastructure Principle

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

Compute Module должен по возможности
работать через бесплатный или
доступный пользователю вычислительный ресурс.

Control Plane при этом не должен
предполагать наличие собственного GPU.

---

# 30. Remote Compute

Compute Module может находиться
в другом Space или сервисе.

Пример:

Control Plane
      ↓
Compute Adapter
      ↓
HTTP/API
      ↓
Remote Space
      ↓
Compute Module

Это является нормальной архитектурной схемой.

---

# 31. Local Compute

Compute Module также может находиться
на том же сервере или в том же окружении.

Пример:

Control Plane
      ↓
Compute Adapter
      ↓
Local Compute Module

Архитектура не должна зависеть
от конкретного способа размещения.

---

# 32. Replaceability

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

Например:

Apckeyl_RealESRGAN

может быть заменён на:

Apckeyl_Upscaler_B

без переписывания:

- Task Manager;
- Dispatcher;
- Control Plane;
- Module Registry.

---

# 33. Versioning

Compute Module должен иметь
собственную версию.

Пример:

Apckeyl_RealESRGAN

Version 1.0

Изменение интерфейса Compute Module
должно сопровождаться изменением версии.

---

# 34. Compatibility

Compute Adapter отвечает
за совместимость Framework
с конкретным Compute Module.

Это позволяет:

Framework API

оставаться стабильным,

даже если внутренний API
Compute Module изменяется.

---

# 35. Future Architecture

В будущем Framework может содержать:

Control Plane
      ↓
Dispatcher
      ↓
Compute Adapter Registry
      ↓
+-----------------------------+
|                             |
↓                             ↓
Image Upscaler          Image Generator
|                             |
↓                             ↓
RealESRGAN                 Generator
|
↓
Image Restoration
|
↓
Restoration Model

---

# 36. Current Stage

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

- Control Plane;
- Module Registry;
- Task Manager;
- Dispatcher;
- Compute Adapter;
- тесты основных компонентов;
- Unified Test Suite;
- Diagnostic Report.

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

- реальный HTTP dispatch;
- удалённый вызов Space;
- authentication между Spaces;
- обработка реального изображения;
- автоматическое масштабирование;
- production queue;
- retry system.

---

# 37. Следующий этап

Следующим этапом является создание
реального Compute Module contract
в коде.

После этого будет создан адаптер:

Apckeyl_RealESRGAN Adapter

который сможет связывать:

Apckeyl Framework

с

Apckeyl_RealESRGAN.

---

# 38. Главное архитектурное правило

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

Dispatcher маршрутизирует.

Compute Adapter соединяет.

Compute Module вычисляет.

Ни один слой не должен брать
на себя ответственность другого слоя.

---

# END OF COMPUTE MODULE CONTRACT
# Version 1.0