ameva-runtime 1.0.0__py3-none-any.whl

ameva_runtime/__init__.py

@@ -0,0 +1,64 @@
+"""
+AMEVA Runtime (Unified Next-Gen On-Device AI Runtime)
+=====================================================
+Multi-backend hardware orchestration (Vulkan, OpenCL, NPU, CPU-NEON)
+for mobile & edge devices.
+"""
+from __future__ import annotations
+
+from .core import (
+    AmevaRuntime,
+    get_runtime,
+    VulkanContext,
+    create_context,
+    get_or_create_context,
+    run,
+    plan,
+    ExecutionResult,
+)
+from .detector import detect_hardware, HardwareProfile
+from .router import SmartRouter, ExecutionPlan, get_router
+from .doctor import Doctor, DiagnosticReport, diagnose
+from .protocol import IRuntimeConsumer, IVulkanConsumer, BindingResult
+from .exceptions import (
+    AmevaRuntimeError,
+    HardwareDetectionError,
+    SubsystemInitError,
+    DriverLockupError,
+    DeviceOOMError,
+    ArchitectureUnsupportedError,
+    InvalidAffinityError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "AmevaRuntime",
+    "get_runtime",
+    "run",
+    "plan",
+    "ExecutionResult",
+    "VulkanContext",
+    "create_context",
+    "get_or_create_context",
+    "detect_hardware",
+    "HardwareProfile",
+    "SmartRouter",
+    "ExecutionPlan",
+    "get_router",
+    "Doctor",
+    "DiagnosticReport",
+    "diagnose",
+    "IRuntimeConsumer",
+    "IVulkanConsumer",
+    "BindingResult",
+    "AmevaRuntimeError",
+    "HardwareDetectionError",
+    "SubsystemInitError",
+    "DriverLockupError",
+    "DeviceOOMError",
+    "ArchitectureUnsupportedError",
+    "InvalidAffinityError",
+]
+

ameva_runtime/adapters/__init__.py

@@ -0,0 +1,23 @@
+"""
+AMEVA Modality Adapters
+=======================
+Adapters connecting individual uno-km AI modalities to the smart runtime.
+"""
+from .base import BindingResult, find_system_vulkan_driver_dir
+from .llamacpp import LlamaCppAdapter
+from .vision import VisionAdapter
+from .diffusion import DiffusionAdapter
+from .stt import SttAdapter
+from .tts import TtsAdapter
+from .bitnet import BitnetAdapter
+
+__all__ = [
+    "BindingResult",
+    "find_system_vulkan_driver_dir",
+    "LlamaCppAdapter",
+    "VisionAdapter",
+    "DiffusionAdapter",
+    "SttAdapter",
+    "TtsAdapter",
+    "BitnetAdapter",
+]

ameva_runtime/adapters/base.py

@@ -0,0 +1,67 @@
+"""
+ameva_runtime.adapters.base
+===========================
+Base Utilities and Shared Helper Functions for AMEVA Modality Adapters.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional, Dict
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from ..router import get_router, SmartRouter
+
+logger = logging.getLogger("ameva_runtime.adapters")
+
+_ADRENO_VENDOR_ID = 0x5143
+_MALI_VENDOR_ID = 0x13B5
+
+
+def _is_vulkan_viable(profile: HardwareProfile) -> bool:
+    """Returns True if Vulkan execution is genuinely safe without driver lockup."""
+    return profile.recommended_backend == "vulkan" and not profile.hardware_hazard
+
+
+def _make_adaptive_binding(
+    module: str,
+    profile: HardwareProfile,
+    config: Dict[str, Any],
+    backend: str = "cpu_neon",
+    status: str = "BOUND_ADAPTIVE",
+) -> BindingResult:
+    """Creates a transparent BindingResult adhering to Zero-Silent-Fallback."""
+    logger.info(
+        "[ameva-runtime:%s] Active Backend: %s (Reason: %s)",
+        module, backend, profile.diagnosis_reason
+    )
+    config["backend"] = backend
+    config["diagnosis"] = profile.diagnosis_reason
+    is_vk = (backend == "vulkan")
+    return BindingResult(
+        module=module,
+        backend=backend,
+        is_vulkan=is_vk,
+        device_name=profile.gpu_family,
+        vendor_id=_MALI_VENDOR_ID if profile.gpu_family == "mali" else _ADRENO_VENDOR_ID,
+        config=config,
+        status=status,
+        diagnosis=profile.diagnosis_reason,
+    )
+
+
+def find_system_vulkan_driver_dir() -> Optional[str]:
+    """Dynamically finds the directory containing the active libvulkan.so."""
+    is_64bit = sys.maxsize > 2**32
+    candidates = [
+        Path("/system/lib64" if is_64bit else "/system/lib"),
+        Path("/vendor/lib64" if is_64bit else "/vendor/lib"),
+        Path("/apex/com.android.runtime/lib64" if is_64bit else "/apex/com.android.runtime/lib"),
+    ]
+    for c in candidates:
+        if (c / "libvulkan.so").exists():
+            return str(c.resolve())
+    return None

ameva_runtime/adapters/bitnet.py

@@ -0,0 +1,50 @@
+"""
+BitnetAdapter — termux-bitnet (1-bit LLM) Acceleration Adapter
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.bitnet")
+
+
+class BitnetAdapter:
+    """termux-bitnet acceleration adapter."""
+
+    module_name = "termux-bitnet"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if not isinstance(profile, HardwareProfile):
+            profile = detect_hardware()
+
+        config: dict = {
+            "module": BitnetAdapter.module_name,
+            "device_name": profile.gpu_family,
+            "backend": "cpu_neon",  # BitNet is natively optimized for CPU 1-bit LUTs
+            "threads": profile.recommended_threads,
+        }
+
+        if engine is not None:
+            try:
+                if hasattr(engine, "threads"):
+                    engine.threads = profile.recommended_threads
+            except Exception as e:
+                logger.warning("Failed to configure BitNet engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=BitnetAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend="cpu_neon",
+            status="BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass

ameva_runtime/adapters/diffusion.py

@@ -0,0 +1,50 @@
+"""
+DiffusionAdapter — termux-diffusion (Stable Diffusion / Onnx / NCNN) Acceleration Adapter
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.diffusion")
+
+
+class DiffusionAdapter:
+    """termux-diffusion acceleration adapter."""
+
+    module_name = "termux-diffusion"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if not isinstance(profile, HardwareProfile):
+            profile = detect_hardware()
+
+        is_vk = profile.recommended_backend == "vulkan"
+        config: dict = {
+            "module": DiffusionAdapter.module_name,
+            "device_name": profile.gpu_family,
+            "backend": "vulkan" if is_vk else "cpu_neon",
+        }
+
+        if engine is not None:
+            try:
+                if hasattr(engine, "device"):
+                    engine.device = "vulkan" if is_vk else "cpu"
+            except Exception as e:
+                logger.warning("Failed to configure diffusion engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=DiffusionAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend="vulkan" if is_vk else "cpu_neon",
+            status="BOUND_VULKAN" if is_vk else "BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass

ameva_runtime/adapters/llamacpp.py

@@ -0,0 +1,88 @@
+"""
+ameva_runtime.adapters.llamacpp
+===============================
+Adapter for termux-llamacpp (GGUF LLM) inference.
+Integrates with SmartRouter to provide Zero-Crash adaptive execution.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from ..router import SmartRouter, ExecutionPlan
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.llamacpp")
+
+
+class LlamaCppAdapter:
+    """termux-llamacpp execution and acceleration adapter."""
+
+    module_name = "termux-llamacpp"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if isinstance(profile, HardwareProfile):
+            prof = profile
+        else:
+            prof = detect_hardware()
+
+        router = SmartRouter(prof)
+        plan: ExecutionPlan = router.route_for_llm()
+
+        config: dict = {
+            "module": LlamaCppAdapter.module_name,
+            "backend": plan.backend,
+            "ngl": plan.ngl,
+            "threads": plan.threads,
+            "cli_flags": plan.cli_flags,
+            "allowed_cpus": plan.allowed_cpus,
+            "is_gpu": plan.is_gpu_accelerated,
+            "diagnosis": plan.diagnosis,
+        }
+
+        # Apply environment overrides
+        for k, v in plan.env_overrides.items():
+            os.environ[k] = v
+
+        if engine is not None:
+            try:
+                if isinstance(engine, dict):
+                    engine["ngl"] = plan.ngl
+                    engine["threads"] = plan.threads
+                    engine["backend"] = plan.backend
+                    engine.setdefault("cli_flags", []).extend(plan.cli_flags)
+                    engine.setdefault("env", {}).update(plan.env_overrides)
+                elif hasattr(engine, "config"):
+                    cfg = engine.config
+                    if isinstance(cfg, dict):
+                        cfg["ngl"] = plan.ngl
+                        cfg["n_gpu_layers"] = plan.ngl
+                        cfg["threads"] = plan.threads
+                        cfg["backend"] = plan.backend
+                    else:
+                        if hasattr(cfg, "ngl"):
+                            cfg.ngl = plan.ngl
+                        if hasattr(cfg, "n_gpu_layers"):
+                            cfg.n_gpu_layers = plan.ngl
+                        if hasattr(cfg, "threads"):
+                            cfg.threads = plan.threads
+                        if hasattr(cfg, "device"):
+                            cfg.device = "vulkan" if plan.is_gpu_accelerated else "cpu"
+            except Exception as e:
+                logger.warning("Failed to inject configuration into engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=LlamaCppAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend=plan.backend,
+            status="BOUND_VULKAN" if plan.is_gpu_accelerated else "BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass

ameva_runtime/adapters/stt.py

@@ -0,0 +1,50 @@
+"""
+SttAdapter — termux-stt (Whisper) Acceleration Adapter
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.stt")
+
+
+class SttAdapter:
+    """termux-stt acceleration adapter."""
+
+    module_name = "termux-stt"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if not isinstance(profile, HardwareProfile):
+            profile = detect_hardware()
+
+        is_vk = profile.recommended_backend == "vulkan"
+        config: dict = {
+            "module": SttAdapter.module_name,
+            "device_name": profile.gpu_family,
+            "backend": "vulkan" if is_vk else "cpu_neon",
+        }
+
+        if engine is not None:
+            try:
+                if hasattr(engine, "device"):
+                    engine.device = "vulkan" if is_vk else "cpu"
+            except Exception as e:
+                logger.warning("Failed to configure STT engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=SttAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend="vulkan" if is_vk else "cpu_neon",
+            status="BOUND_VULKAN" if is_vk else "BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass

ameva_runtime/adapters/tts.py

@@ -0,0 +1,50 @@
+"""
+TtsAdapter — termux-tts (Piper / Kokoro) Acceleration Adapter
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.tts")
+
+
+class TtsAdapter:
+    """termux-tts acceleration adapter."""
+
+    module_name = "termux-tts"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if not isinstance(profile, HardwareProfile):
+            profile = detect_hardware()
+
+        is_vk = profile.recommended_backend == "vulkan"
+        config: dict = {
+            "module": TtsAdapter.module_name,
+            "device_name": profile.gpu_family,
+            "backend": "vulkan" if is_vk else "cpu_neon",
+        }
+
+        if engine is not None:
+            try:
+                if hasattr(engine, "device"):
+                    engine.device = "vulkan" if is_vk else "cpu"
+            except Exception as e:
+                logger.warning("Failed to configure TTS engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=TtsAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend="vulkan" if is_vk else "cpu_neon",
+            status="BOUND_VULKAN" if is_vk else "BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass

ameva_runtime/adapters/vision.py

@@ -0,0 +1,51 @@
+"""
+VisionAdapter — termux-vision (LLaVA ViT / YOLO) Acceleration Adapter
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..protocol import BindingResult
+from ..detector import detect_hardware, HardwareProfile
+from .base import _make_adaptive_binding
+
+logger = logging.getLogger("ameva_runtime.adapters.vision")
+
+
+class VisionAdapter:
+    """termux-vision (LLaVA ViT / SmolVLM / YOLO) acceleration adapter."""
+
+    module_name = "termux-vision"
+
+    @staticmethod
+    def bind(engine: Any = None, profile: Any = None) -> BindingResult:
+        if not isinstance(profile, HardwareProfile):
+            profile = detect_hardware()
+
+        is_vk = profile.recommended_backend == "vulkan"
+        config: dict = {
+            "module": VisionAdapter.module_name,
+            "device_name": profile.gpu_family,
+            "backend": "vulkan" if is_vk else "cpu_neon",
+            "vit_acceleration": is_vk,
+        }
+
+        if engine is not None:
+            try:
+                if hasattr(engine, "device"):
+                    engine.device = "vulkan" if is_vk else "cpu"
+            except Exception as e:
+                logger.warning("Failed to configure vision engine: %s", e)
+
+        return _make_adaptive_binding(
+            module=VisionAdapter.module_name,
+            profile=profile,
+            config=config,
+            backend="vulkan" if is_vk else "cpu_neon",
+            status="BOUND_VULKAN" if is_vk else "BOUND_CPU_NEON",
+        )
+
+    @staticmethod
+    def unbind() -> None:
+        pass