amv-diffusion 2.1.0__py3-none-any.whl

termux_diffusion/doctor.py

@@ -0,0 +1,128 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+termux_diffusion.doctor
+=======================
+Pre-flight diagnostics, hardware topology inspection, and system verification for termux-diffusion.
+"""
+
+import os
+import sys
+import shutil
+import logging
+from pathlib import Path
+from typing import Optional
+
+from .platform import (
+    is_android_termux,
+    is_arm64,
+    get_memory_info,
+    check_memory_safety,
+)
+
+logger = logging.getLogger("termux_diffusion.doctor")
+
+
+def run_doctor() -> bool:
+    """Run comprehensive 8-tier pre-flight diagnostic checks for Samsung Galaxy Termux setup."""
+    from .engine import get_binary_path
+
+    print("=" * 65)
+    print("[Doctor] [termux-diffusion] Pre-flight Diagnostic Doctor")
+    print("=" * 65)
+
+    all_passed = True
+
+    # 1. Platform Check
+    is_termux = is_android_termux()
+    arm_arch = is_arm64()
+    print(f"1. Platform: {'Android Termux [OK]' if is_termux else 'Non-Termux Host (Emulation Mode) [INFO]'}")
+    print(f"2. Architecture: {'ARM64 / aarch64 [OK]' if arm_arch else f'Host {sys.platform} ({os.name}) [INFO]'}")
+
+    # 3. Memory & RAM Plus
+    mem = get_memory_info()
+    safe, msg = check_memory_safety(required_mb=1200)
+    print(f"3. System Memory: {mem['mem_total_mb']}MB RAM + {mem['swap_total_mb']}MB Swap ({'Safe [OK]' if safe else 'Warning [WARN]'})")
+    if not safe:
+        print(f"   -> {msg}")
+
+    # 4. Storage & Samsung Gallery
+    storage_ok = os.path.exists(os.path.expanduser("~/storage"))
+    print(f"4. Android Storage Permission: {'Configured [OK]' if storage_ok else 'Missing [WARN] (Run termux-setup-storage)'}")
+
+    # 5. Compiler Toolchain
+    clang_ok = bool(shutil.which("clang") or shutil.which("gcc") or shutil.which("clang++"))
+    cmake_ok = bool(shutil.which("cmake"))
+    git_ok = bool(shutil.which("git"))
+    print(f"5. Build Tools: clang ({'[OK]' if clang_ok else '[FAIL]'}), cmake ({'[OK]' if cmake_ok else '[FAIL]'}), git ({'[OK]' if git_ok else '[FAIL]'})")
+    if not (clang_ok and cmake_ok and git_ok) and is_termux:
+        all_passed = False
+        print("   -> Run: pkg install clang cmake git termux-api -y")
+
+    # 6. Engine Binary
+    engine = get_binary_path()
+    print(f"6. Native C++ Engine (sd-cli): {str(engine) + ' [OK]' if engine else 'Not Provisioned [FAIL] (Run termux-diffusion install)'}")
+    if not engine:
+        all_passed = False
+
+    # 7. Model Cache Status
+    from .hub import list_cached_models
+    cached = list_cached_models()
+    print(f"7. Cached GGUF Models: {len(cached)} model(s) available locally.")
+    for m in cached:
+        valid_tag = " [GGUF Valid [OK]]" if m.get("is_valid_gguf") else " [Header [WARN]]"
+        print(f"   -> {m['name']} ({m['size_mb']} MB){valid_tag}")
+
+    # 8. Hardware Acceleration (GPU / NPU / TPU / Vulkan / OpenCL)
+    try:
+        from ameva_runtime.vulkan.adapters import find_system_vulkan_driver_dir
+        discovered_vulkan = find_system_vulkan_driver_dir()
+    except ImportError:
+        discovered_vulkan = None
+
+    from .hardware import detect_hardware_profile
+    hw = detect_hardware_profile()
+    print("8. Hardware Acceleration Profile:")
+    print(f"   SoC: {hw.soc_name}, GPU Architecture: {hw.gpu_name}")
+    print(f"   GPU Vulkan: {'Available [OK]' if (hw.vulkan_available or discovered_vulkan) else 'Not Found [WARN]'}")
+    if discovered_vulkan:
+        print(f"     -> Vulkan Driver (ameva-runtime): {discovered_vulkan}")
+    elif hw.vulkan_driver:
+        print(f"     -> Vulkan Driver: {hw.vulkan_driver.library_path}")
+    print(f"   GPU OpenCL: {'Available [OK]' if hw.opencl_available else 'Not Found [WARN]'}")
+    if hw.opencl_driver:
+        print(f"     -> OpenCL Driver: {hw.opencl_driver.library_path}")
+    if hw.npu_profile and hw.npu_profile.available:
+        print("   NPU / TPU Hardware: Detected [INFO]")
+        print(f"     -> Architecture: {hw.npu_profile.dsp_architecture} ({hw.npu_profile.tops_rating} TOPS)")
+        print(f"     -> Driver: {hw.npu_profile.driver_library}")
+        print("     -> Runtime: Native QNN C++ execution scheduled for v2.0")
+    else:
+        print("   NPU / TPU Hardware: Not Detected [INFO] (GPU Vulkan & CPU NEON Active)")
+    print(f"   CPU ISA SIMD: DotProd={'[OK]' if hw.has_dotprod else '[FAIL]'} "
+          f"FP16={'[OK]' if hw.has_fp16 else '[FAIL]'} "
+          f"I8MM={'[OK]' if hw.has_i8mm else '[FAIL]'} "
+          f"SVE={'[OK]' if hw.has_sve else '[FAIL]'}")
+    print(f"   Active Compute Pipeline: {hw.recommended_backend.value.upper()} "
+          f"(Offload Layers: {hw.recommended_ngl})")
+
+    # 9. Prompt Cache & Auxiliary Assets Status
+    from .platform import get_default_cache_dir
+    cache_dir = get_default_cache_dir() / "prompt_cache"
+    cache_count = len(list(cache_dir.glob("*"))) if cache_dir.is_dir() else 0
+    print(f"9. Auxiliary Assets & Prompt Cache: {cache_count} cached entries at {cache_dir} [OK]")
+
+    # 10. Android 12+ Background Stability Guard (Phantom Process Killer)
+    if is_termux:
+        print("10. Android 12+ Background Guard:")
+        print("   -> Tip: If generation crashes when Termux is in background, enable")
+        print("          'Developer Options > Disable child process restrictions'")
+        print("          or run: adb shell \"/system/bin/device_config put activity_manager max_phantom_processes 2147483647\"")
+
+    print("=" * 65)
+    if all_passed:
+        print("All core diagnostics passed. System is ready for AI image generation.")
+    else:
+        print("Some diagnostics need attention. Run 'termux-diffusion install' to resolve.")
+    print("=" * 65)
+    return all_passed

termux_diffusion/downloader.py

@@ -0,0 +1,111 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""Atomic download manager with SHA-256 integrity verification, concurrency lock, and rollback safety."""
+
+import os
+import shutil
+import time
+import urllib.request
+import logging
+from pathlib import Path
+from typing import Optional
+
+from .exceptions import DownloadError, InstallLockError, TermuxDiffusionError
+from .locking import InstallLock
+from .manifest import verify_file_sha256
+
+logger = logging.getLogger("termux_diffusion.downloader")
+
+
+def atomic_download_file(
+    url: str,
+    dest_path: Path,
+    expected_sha256: Optional[str] = None,
+    expected_size: Optional[int] = None,
+    timeout_sec: float = 120.0,
+    user_agent: str = "termux-diffusion-downloader/1.2.0"
+) -> Path:
+    """Download url to dest_path atomically using .part -> SHA256 check -> atomic rename -> rollback."""
+    dest_path.parent.mkdir(parents=True, exist_ok=True)
+    part_path = dest_path.with_suffix(dest_path.suffix + ".part")
+    bak_path = dest_path.with_suffix(dest_path.suffix + ".bak")
+
+    part_path.unlink(missing_ok=True)
+    bak_path.unlink(missing_ok=True)
+
+    print(f"[termux-diffusion] Downloading artifact from {url}...")
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": user_agent})
+        with urllib.request.urlopen(req, timeout=timeout_sec) as response:
+            if response.status != 200:
+                raise DownloadError(f"E_ARTIFACT_DOWNLOAD: HTTP server returned status code {response.status}")
+            
+            with open(part_path, "wb") as out_f:
+                shutil.copyfileobj(response, out_f)
+    except Exception as exc:
+        part_path.unlink(missing_ok=True)
+        raise DownloadError(f"E_ARTIFACT_DOWNLOAD: Network error downloading {url}: {exc}") from exc
+
+    # Size Verification
+    actual_size = part_path.stat().st_size
+    if expected_size is not None and expected_size > 0 and actual_size != expected_size:
+        part_path.unlink(missing_ok=True)
+        raise DownloadError(
+            f"E_ARTIFACT_SIZE: Downloaded artifact size mismatch. "
+            f"Expected {expected_size} bytes, got {actual_size} bytes."
+        )
+
+    # SHA-256 Verification
+    if expected_sha256 and not verify_file_sha256(part_path, expected_sha256):
+        part_path.unlink(missing_ok=True)
+        raise DownloadError(
+            f"E_ARTIFACT_SHA256: SHA-256 checksum verification failed for {dest_path.name}. "
+            f"Artifact hash mismatch!"
+        )
+
+    # Atomic Rename with Backup Rollback Safety
+    try:
+        if dest_path.exists():
+            dest_path.rename(bak_path)
+        part_path.rename(dest_path)
+        os.chmod(dest_path, 0o755)
+        bak_path.unlink(missing_ok=True)
+        print(f"[termux-diffusion] Artifact {dest_path.name} downloaded and verified (SHA-256 match).")
+        return dest_path
+    except Exception as e:
+        # Rollback
+        part_path.unlink(missing_ok=True)
+        if bak_path.exists() and not dest_path.exists():
+            bak_path.rename(dest_path)
+        raise DownloadError(f"E_ATOMIC_RENAME_FAIL: Failed installing verified artifact {dest_path.name}: {e}") from e
+
+
+from typing import List, Dict, Any, Union
+
+
+def list_models() -> List[Dict[str, Any]]:
+    """List standard verified diffusion models from hub presets."""
+    from .hub import list_presets
+    presets = list_presets()
+    return [{"id": k, **v} for k, v in presets.items()]
+
+
+def download_model(
+    model_name_or_url: str = "sdxs",
+    cache_dir: Optional[Union[str, Path]] = None,
+    force: bool = False,
+    **kwargs: Any,
+) -> Path:
+    """Download diffusion model weights using termux_diffusion.hub."""
+    from .hub import download_model as _hub_download
+    return _hub_download(model_name_or_url=model_name_or_url, cache_dir=cache_dir, force=force, **kwargs)
+
+
+def resolve_model_path(
+    model_name_or_path: str = "sdxs",
+    cache_dir: Optional[Union[str, Path]] = None,
+) -> Path:
+    """Resolve diffusion model path to local Path."""
+    from .hub import resolve_model_path as _hub_resolve
+    return _hub_resolve(model_name_or_path=model_name_or_path, cache_dir=cache_dir)
+

termux_diffusion/engine.py

@@ -0,0 +1,226 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+termux_diffusion.engine
+=======================
+High-performance C++ core engine locator, backend dispatcher, and high-level DiffusionEngine wrapper.
+Strict Zero-Silent-Fallback and Anti-Deception compliant architecture matching AMEVA standards.
+"""
+
+import os
+import sys
+import shutil
+import logging
+from pathlib import Path
+from typing import Optional, List, Dict, Any, Union
+
+from .platform import (
+    TERMUX_PREFIX,
+    is_android_termux,
+    get_default_cache_dir,
+)
+
+logger = logging.getLogger("termux_diffusion.engine")
+
+
+def get_engine_bin_dir() -> Path:
+    """Return canonical directory where termux-diffusion binaries reside ($PREFIX/bin SSOT)."""
+    prefix = os.environ.get("PREFIX") or TERMUX_PREFIX
+    if is_android_termux() or os.path.exists(prefix):
+        bin_dir = Path(prefix) / "bin"
+    else:
+        bin_dir = get_default_cache_dir() / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    return bin_dir
+
+
+def get_engine_lib_dir() -> Path:
+    """Return canonical directory where native shared libraries reside ($PREFIX/lib SSOT)."""
+    prefix = os.environ.get("PREFIX") or TERMUX_PREFIX
+    if is_android_termux() or os.path.exists(prefix):
+        lib_dir = Path(prefix) / "lib"
+    else:
+        lib_dir = get_default_cache_dir() / "lib"
+    lib_dir.mkdir(parents=True, exist_ok=True)
+    return lib_dir
+
+
+def get_binary_path(backend: str = "auto") -> Optional[Path]:
+    """Find authoritative absolute path of sd-cli executable strictly isolated by compute backend.
+    
+    Zero-Silent-Fallback Rules:
+    - 'gpu' / 'vulkan': Exclusively search for native Vulkan binary (sd-cli-vulkan).
+                        Never fallback to CPU binary. Return None if unprovisioned.
+    - 'cpu' / default:  Exclusively search for pure CPU NEON binary (sd-cli-cpu, sd-cli).
+    """
+    home = Path(os.environ.get("HOME", os.path.expanduser("~")))
+    prefix_bin = Path(TERMUX_PREFIX) / "bin"
+    bin_dir = get_engine_bin_dir()
+    ameva_diff_dir = home / ".local" / "share" / "ameva" / "current" / "diffusion"
+
+    req_backend = str(backend or "auto").strip().lower()
+
+    # --------------------------------------------------------------------------
+    # 0. RPC / Distributed Multi-Node Route (sd-cli-rpc, sd-cli)
+    # --------------------------------------------------------------------------
+    if req_backend in ("rpc", "remote"):
+        rpc_candidates = [
+            ameva_diff_dir / "sd-cli-rpc",
+            home / ".local" / "share" / "ameva" / "rpc_llama" / "bin" / "sd-cli",
+            home / ".local" / "share" / "ameva" / "rpc_llama" / "bin" / "sd-cli-rpc",
+            bin_dir / "sd-cli-rpc",
+            prefix_bin / "sd-cli-rpc",
+            home / ".local" / "bin" / "sd-cli-rpc",
+            bin_dir / "sd-cli",
+            prefix_bin / "sd-cli",
+        ]
+        for p in rpc_candidates:
+            if p.is_file() and (os.access(p, os.X_OK) or os.name == "nt"):
+                return p.resolve()
+
+        which_rpc = shutil.which("sd-cli-rpc")
+        if which_rpc and (os.access(which_rpc, os.X_OK) or os.name == "nt"):
+            return Path(which_rpc).resolve()
+
+    # --------------------------------------------------------------------------
+    # 1. GPU / Vulkan Route: Pure Vulkan GPU Binary (sd-cli-vulkan)
+    # --------------------------------------------------------------------------
+    if req_backend in ("vulkan", "gpu"):
+        vulkan_candidates = [
+            # AMEVA 2-Tier isolated current deployment
+            ameva_diff_dir / "sd-cli-vulkan",
+            # Termux prefix binary
+            prefix_bin / "sd-cli-vulkan",
+            bin_dir / "sd-cli-vulkan",
+            # User local binary
+            home / ".local" / "bin" / "sd-cli-vulkan",
+        ]
+        for p in vulkan_candidates:
+            if p.is_file() and (os.access(p, os.X_OK) or os.name == "nt"):
+                return p.resolve()
+
+        # System PATH search strictly for 'sd-cli-vulkan'
+        which_vk = shutil.which("sd-cli-vulkan")
+        if which_vk and (os.access(which_vk, os.X_OK) or os.name == "nt"):
+            return Path(which_vk).resolve()
+
+        # Zero-Silent-Fallback: If Vulkan binary is absent, NEVER return CPU binary!
+        return None
+
+    # --------------------------------------------------------------------------
+    # 1.1 OpenCL Route: OpenCL GPU Binary (sd-cli with OpenCL)
+    # --------------------------------------------------------------------------
+    if req_backend in ("opencl", "cl"):
+        opencl_candidates = [
+            home / "sd-opencl-build" / "build" / "bin" / "sd-cli",
+            bin_dir / "sd-cli-opencl",
+            prefix_bin / "sd-cli-opencl",
+            prefix_bin / "sd-cli",
+        ]
+        for p in opencl_candidates:
+            if p.is_file() and (os.access(p, os.X_OK) or os.name == "nt"):
+                return p.resolve()
+        return None
+
+    # --------------------------------------------------------------------------
+    # 2. CPU Baseline Route: Pure CPU NEON Binary (sd-cli-cpu, sd-cli)
+    # --------------------------------------------------------------------------
+    cpu_candidates = [
+        home / ".local" / "share" / "ameva" / "rpc_llama" / "bin" / "sd-cli",
+        bin_dir / "sd-cli-cpu",
+        prefix_bin / "sd-cli-cpu",
+        bin_dir / "sd-cli-source-cpu",
+        bin_dir / "sd-cli",
+        prefix_bin / "sd-cli",
+        home / ".local" / "bin" / "sd-cli-cpu",
+        home / ".local" / "bin" / "sd-cli",
+    ]
+    for p in cpu_candidates:
+        if p.is_file() and (os.access(p, os.X_OK) or os.name == "nt"):
+            return p.resolve()
+
+    # System PATH search for CPU binary
+    for name in ("sd-cli", "sd-cli.exe", "sd", "sd.exe"):
+        which_path = shutil.which(name)
+        if which_path and (os.access(which_path, os.X_OK) or os.name == "nt"):
+            return Path(which_path).resolve()
+
+    return None
+
+
+def locate_sd_cli(backend: Optional[str] = None) -> Optional[Path]:
+    """Backward-compatible alias for get_binary_path."""
+    return get_binary_path(backend=backend or "auto")
+
+
+class DiffusionEngine:
+    """High-level Python SDK Engine for On-Device Stable Diffusion inference.
+    Follows canonical AMEVA component architecture matching LlamaRuntime and BitNetEngine.
+    """
+
+    def __init__(
+        self,
+        model: str = "realistic",
+        backend: str = "auto",
+        device: Optional[str] = None,
+        rpc: Optional[str] = None,
+        tensor_split: Optional[str] = None,
+        cluster_rpc_servers: Optional[Union[str, List[str]]] = None,
+        cluster_split_mode: Optional[str] = None,
+        cluster_tensor_split: Optional[str] = None,
+        cluster_vram_budget: Optional[str] = None,
+        **kwargs: Any,
+    ):
+        self.model = model
+        self.device = device or backend or "auto"
+        self.requested_backend = self.device.strip().lower()
+        self.cluster_rpc_servers = cluster_rpc_servers or rpc
+        self.rpc = self.cluster_rpc_servers if isinstance(self.cluster_rpc_servers, str) else (",".join(self.cluster_rpc_servers) if self.cluster_rpc_servers else None)
+        self.cluster_tensor_split = cluster_tensor_split or tensor_split
+        self.tensor_split = self.cluster_tensor_split
+        self.cluster_split_mode = cluster_split_mode
+        self.cluster_vram_budget = cluster_vram_budget
+        self.bin_dir = get_engine_bin_dir()
+        self.lib_dir = get_engine_lib_dir()
+        self.kwargs = kwargs
+
+    def get_binary_path(self, backend: Optional[str] = None) -> Optional[Path]:
+        """Resolve authoritative binary path for active or specified backend."""
+        target_backend = backend if backend is not None else self.requested_backend
+        return get_binary_path(backend=target_backend)
+
+    def generate(self, prompt: str, **kwargs: Any) -> Any:
+        """Execute text-to-image generation delegating to core pipeline."""
+        from .core import generate
+        merged = {**self.kwargs, **kwargs}
+        merged.setdefault("device", self.requested_backend)
+        merged.setdefault("model", self.model)
+        if self.rpc and "rpc" not in merged:
+            merged["rpc"] = self.rpc
+        if self.cluster_rpc_servers and "cluster_rpc_servers" not in merged:
+            merged["cluster_rpc_servers"] = self.cluster_rpc_servers
+        if self.tensor_split and "tensor_split" not in merged:
+            merged["tensor_split"] = self.tensor_split
+        if self.cluster_split_mode and "cluster_split_mode" not in merged:
+            merged["cluster_split_mode"] = self.cluster_split_mode
+        if self.cluster_tensor_split and "cluster_tensor_split" not in merged:
+            merged["cluster_tensor_split"] = self.cluster_tensor_split
+        if self.cluster_vram_budget and "cluster_vram_budget" not in merged and "max_vram" not in merged:
+            merged["cluster_vram_budget"] = self.cluster_vram_budget
+        return generate(prompt=prompt, **merged)
+
+    @staticmethod
+    def doctor() -> bool:
+        """Run comprehensive pre-flight diagnostic checks."""
+        from .doctor import run_doctor
+        return run_doctor()
+
+
+def load(model: str = "realistic", device: str = "auto", **kwargs: Any) -> DiffusionEngine:
+    """Standard Unified Engine Factory for termux-diffusion matching AMEVA multi-modal standards."""
+    return DiffusionEngine(model=model, device=device, **kwargs)
+
+
+# Backward-compatible alias matching LlamaRuntime
+DiffusionRuntime = DiffusionEngine
+

termux_diffusion/exceptions.py

@@ -0,0 +1,158 @@
+# Copyright (c) 2026 Uno Kim / AMEVA Foundation. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0 OR Commercial-License
+"""
+AMEVA Unified Exception Hierarchy for Termux AI Engines.
+Component: [DIFFUSION]
+"""
+from typing import Optional, Any
+
+
+class AmevaTermuxError(Exception):
+    """Root exception for all Termux On-Device AI Engines."""
+    COMPONENT_TAG = "[DIFFUSION]"
+    DEFAULT_CODE = "E_UNKNOWN"
+
+    def __init__(self, message: str, code: Optional[Any] = None, details: Optional[Any] = None):
+        self.code = code or self.DEFAULT_CODE
+        self.details = details
+        self.raw_message = message
+        super().__init__(message if message.startswith("[DIFFUSION]") else f"{self.COMPONENT_TAG} [{self.code}] {message}")
+
+
+TermuxDiffusionError = AmevaTermuxError
+
+
+class ErrorCode:
+    CLI_EXCLUSIVE = "E_CLI_EXCLUSIVE_MUTEX"
+    PLATFORM_UNSUPPORTED = "E_PLATFORM_UNSUPPORTED"
+    MANIFEST_DOWNLOAD = "E_MANIFEST_DOWNLOAD"
+    MANIFEST_SIGNATURE = "E_MANIFEST_SIGNATURE"
+    MANIFEST_SCHEMA = "E_MANIFEST_SCHEMA"
+    MANIFEST_EXPIRED = "E_MANIFEST_EXPIRED"
+    ARTIFACT_DOWNLOAD = "E_ARTIFACT_DOWNLOAD"
+    ARTIFACT_SIZE = "E_ARTIFACT_SIZE"
+    ARTIFACT_SHA256 = "E_ARTIFACT_SHA256"
+    ARTIFACT_FORMAT = "E_ARTIFACT_FORMAT"
+    DYNAMIC_LINKER = "E_DYNAMIC_LINKER"
+    ILLEGAL_INSTRUCTION = "E_ILLEGAL_INSTRUCTION"
+    PROCESS_TIMEOUT = "E_PROCESS_TIMEOUT"
+    VULKAN_LOADER = "E_VULKAN_LOADER"
+    VULKAN_DEVICE = "E_VULKAN_DEVICE"
+    VULKAN_PIPELINE = "E_VULKAN_PIPELINE"
+    CPU_SELFTEST = "E_CPU_SELFTEST"
+    SOURCE_CLONE = "E_SOURCE_CLONE"
+    SOURCE_PATCH = "E_SOURCE_PATCH"
+    SOURCE_CONFIGURE = "E_SOURCE_CONFIGURE"
+    SOURCE_BUILD = "E_SOURCE_BUILD"
+    SOURCE_ARTIFACT = "E_SOURCE_ARTIFACT"
+    INSTALL_LOCKED = "E_INSTALL_LOCKED"
+    ROLLBACK_FAILED = "E_ROLLBACK_FAILED"
+    CLUSTER_CONNECTION = "E_CLUSTER_CONNECTION"
+    CLUSTER_CONFIG = "E_CLUSTER_CONFIG"
+
+
+class ExitCode:
+    SUCCESS = 0
+    CLI_ERROR = 2
+    PLATFORM_ERROR = 10
+    INTEGRITY_ERROR = 20
+    EXECUTION_ERROR = 30
+    SELFTEST_ERROR = 40
+    RUNTIME_REQUIRED = 69
+    BUILD_ERROR = 50
+    ROLLBACK_ERROR = 60
+
+
+class PlatformNotSupportedError(TermuxDiffusionError):
+    def __init__(self, message: str):
+        super().__init__(message, code=ErrorCode.PLATFORM_UNSUPPORTED)
+
+
+class RuntimeRequiredError(PlatformNotSupportedError):
+    """A GPU request needs ameva-runtime (AMUDA), which is missing or too old.
+
+    The message is the shared AMU_ERR_RUNTIME_REQUIRED explanation. The CLI exits with
+    ExitCode.RUNTIME_REQUIRED; nothing is run and there is no CPU fallback.
+    """
+
+    runtime_required = True
+
+
+class ModelNotFoundError(TermuxDiffusionError):
+    pass
+
+
+class ModelDownloadError(TermuxDiffusionError):
+    pass
+
+
+class DownloadError(TermuxDiffusionError):
+    def __init__(self, message: str, code: str = ErrorCode.ARTIFACT_DOWNLOAD):
+        super().__init__(message, code=code)
+
+
+class ProvisioningError(TermuxDiffusionError):
+    def __init__(self, message: str, code: str = ErrorCode.SOURCE_BUILD):
+        super().__init__(message, code=code)
+
+
+class InstallLockError(TermuxDiffusionError):
+    def __init__(self, message: str):
+        super().__init__(message, code=ErrorCode.INSTALL_LOCKED)
+
+
+class OOMRiskError(TermuxDiffusionError):
+    pass
+
+
+class InferenceTimeoutError(TermuxDiffusionError):
+    pass
+
+
+class HardwareCompatibilityError(TermuxDiffusionError):
+    pass
+
+
+class RuntimeNotFoundError(TermuxDiffusionError):
+    pass
+
+
+class InferenceExecutionError(TermuxDiffusionError):
+    pass
+
+
+class ModelCorruptedError(TermuxDiffusionError):
+    pass
+
+
+class ClusterConnectionError(TermuxDiffusionError):
+    """Raised when one or more distributed RPC worker nodes cannot be reached or fail handshake."""
+    def __init__(self, message: str):
+        super().__init__(message, code=ErrorCode.CLUSTER_CONNECTION)
+
+
+class ClusterConfigurationError(TermuxDiffusionError):
+    """Raised when cluster parameters (tensor split, backend, vram budget) are invalid."""
+    def __init__(self, message: str):
+        super().__init__(message, code=ErrorCode.CLUSTER_CONFIG)
+
+
+class ClusterLicenseRequiredError(TermuxDiffusionError):
+    """Raised when distributed clustering is invoked without required AMEVA Cluster license."""
+    def __init__(self, message: str = ""):
+        if not message:
+            message = (
+                "\n================================================================================\n"
+                "[AMEVA-CLUSTER] CLUSTER LICENSE REQUIRED (E403)\n"
+                "================================================================================\n"
+                "Multi-device distributed clustering is an exclusive capability of 'ameva-cluster'.\n"
+                "Standalone distributed execution without the official AMEVA-Cluster package is prohibited.\n\n"
+                "Resolution:\n"
+                "  1. Install official AMEVA-Cluster runtime:\n"
+                "     pip install ameva-cluster  (or npm install @ameva/cluster)\n"
+                "  2. Launch worker/master through 'ameva-cluster' control plane:\n"
+                "     ameva-cluster worker\n"
+                "     ameva-cluster master -m model.gguf\n"
+                "================================================================================"
+            )
+        super().__init__(message, code=ErrorCode.CLUSTER_CONFIG)