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