ameva-runtime 2.0.2__tar.gz → 2.2.0__tar.gz

ameva_runtime-2.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: ameva-runtime
+Version: 2.2.0
+Summary: Unified Next-Gen Hardware Orchestration & AI Acceleration Runtime for Mobile & Edge
+Home-page: https://github.com/uno-km/ameva-runtime
+Author: Eunho Kim
+Author-email: Eunho Kim <contact@uno-km.com>
+License: Apache-2.0
+Project-URL: Homepage, https://uno-km.vercel.app/lib/vulkan/
+Project-URL: Repository, https://github.com/uno-km/ameva-runtime
+Project-URL: Documentation, https://uno-km.vercel.app/lib/vulkan/
+Keywords: vulkan,opencl,npu,cpu-neon,android,termux,acceleration,adreno,mali,hal,ameva
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Android
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: stt
+Requires-Dist: termux-stt>=1.2.0; extra == "stt"
+Provides-Extra: diffusion
+Requires-Dist: termux-diffusion>=1.5.0; extra == "diffusion"
+Provides-Extra: bitnet
+Requires-Dist: termux-bitnet>=1.2.0; extra == "bitnet"
+Provides-Extra: llamacpp
+Requires-Dist: termux-llamacpp>=1.3.0; extra == "llamacpp"
+Provides-Extra: tts
+Requires-Dist: termux-tts>=1.4.0; extra == "tts"
+Provides-Extra: vision
+Requires-Dist: termux-vision>=1.2.0; extra == "vision"
+Provides-Extra: all
+Requires-Dist: termux-stt>=1.2.0; extra == "all"
+Requires-Dist: termux-diffusion>=1.5.0; extra == "all"
+Requires-Dist: termux-bitnet>=1.2.0; extra == "all"
+Requires-Dist: termux-llamacpp>=1.3.0; extra == "all"
+Requires-Dist: termux-tts>=1.4.0; extra == "all"
+Requires-Dist: termux-vision>=1.2.0; extra == "all"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# AMEVA-Runtime (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/ameva-runtime.svg?style=flat-square&color=0369a1)](https://pypi.org/project/ameva-runtime/)
+[![Python](https://img.shields.io/pypi/pyversions/ameva-runtime.svg?style=flat-square)](https://pypi.org/project/ameva-runtime/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/ameva-runtime)
+
+> Next-Gen Unified On-Device Hardware Orchestration & 6-Modality AI Acceleration Runtime for Mobile & Edge
+
+## Installation
+
+```bash
+pip install ameva-runtime
+```
+
+## Quickstart
+
+```python
+import ameva_runtime as ameva
+from ameva_runtime import vulkan
+
+# Inspect hardware
+profile = ameva.detect_hardware()
+print(f"Target: {profile.soc_name} | {profile.gpu_vendor}")
+
+# Run diagnostics
+doc = vulkan.Doctor()
+report = doc.run_self_test()
+print(f"Passed: {report.passed_stages}/{report.total_stages}")
+```
+
+## Empirical Benchmarks
+
+- **Galaxy S25 (Adreno 830)**: LLM 35.80 t/s (VRAM 25/25 layers), Whisper STT 4,401 ms, TTS RTF 0.264x (medium) / 0.993x (high-fp16).
+- **Galaxy A35 (Mali-G68 MP5)**: LLM 4.44 t/s (+26.9% vs NEON), Whisper STT 360.60s (2.26x speedup), TTS RTF 1.146x.
+
+## Documentation
+- [Official Documentation](https://uno-km.vercel.app/lib/vulkan/)
+- [GitHub Repository](https://github.com/uno-km/ameva-runtime)
+
+## License
+Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).

ameva_runtime-2.2.0/README.md

@@ -0,0 +1,111 @@
+# AMEVA-Runtime
+
+[![PyPI](https://img.shields.io/pypi/v/ameva-runtime.svg?style=flat-square&color=0369a1)](https://pypi.org/project/ameva-runtime/)
+[![Python](https://img.shields.io/pypi/pyversions/ameva-runtime.svg?style=flat-square)](https://pypi.org/project/ameva-runtime/)
+[![npm](https://img.shields.io/npm/v/@ameva/runtime.svg?style=flat-square&color=b91c1c)](https://www.npmjs.com/package/@ameva/runtime)
+[![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/ameva-runtime)
+
+> Next-Gen Unified On-Device Hardware Orchestration & 6-Modality AI Acceleration Runtime for Mobile & Edge
+
+---
+
+## Architecture & Overview
+
+AMEVA-Runtime is a hardware abstraction layer (HAL) and compute orchestration engine engineered specifically for mobile ARM64 devices (Android Termux, Linux Edge). It continuously inspects underlying silicon topology (/dev/kgsl-3d0, /dev/mali0) to route tensor execution across Qualcomm Adreno, ARM Mali, and ARM Cortex CPU-NEON backends.
+
+### 6-Modality Acceleration Matrix
+
+| Modality | Engine Integration | Status (v2.1.0) | Hardware Acceleration Mechanism |
+| :--- | :--- | :---: | :--- |
+| **1. LLM (Text)** | Llama.cpp (Qwen2.5, Llama 3.2) | **Production** | Full 25/25 layer VRAM offload (Adreno 35.80 t/s, Mali 4.44 t/s) |
+| **2. STT (Speech)** | Whisper.cpp (Large-v3-Turbo) | **Production** | Vulkan compute shader acceleration (Adreno 4.4s, Mali 2.26x speedup) |
+| **3. TTS (Audio)** | Sherpa-NCNN / Piper | **Production** | Pure Vulkan GPU neural synthesis (Adreno RTF 0.264x, Mali RTF 1.146x) |
+| **4. Vision (VLM)** | CLIP / MobileVLM / LLaVA | **In Development** | GGML Vulkan vision encoder tensor bindings |
+| **5. Diffusion (Image)** | Stable Diffusion v1.5 / FLUX.1 | **In Development** | On-device Vulkan UNet & DiT tensor offload |
+| **6. Train (Training)** | On-Device LoRA / QLoRA | **In Development** | Mobile Vulkan gradient descent backpropagation |
+
+---
+
+## Empirical Physical Device Benchmarks
+
+Tested on physical devices running Android 16 under Termux ARM64:
+
+### 1. LLM Generation (Qwen2.5-0.5B-Instruct Q4_K_M)
+| Target Device | Hardware Architecture | Active Backend | Layers in VRAM | Generation Speed | Prompt Processing | Speedup |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | Vulkan 1.3 | **25/25 (100%)** | **35.80 t/s** (27.9 ms/t) | 4.53 t/s | **35.8x (vs CPU)** |
+| **Galaxy A35** | Exynos 1380 / ARM Mali-G68 MP5 | Vulkan 1.3 | **25/25 (100%)** | **4.44 t/s** (225 ms/t) | 6.12 t/s | **+26.9% (vs NEON)** |
+| **Galaxy A35** | Cortex-A78 CPU-NEON (3 Threads) | CPU-NEON | 0/25 | 3.55 t/s (281 ms/t) | 8.05 t/s | Baseline |
+
+### 2. Speech-to-Text (Whisper Large-v3-Turbo Q5_0, 548MB)
+| Target Device | Hardware Architecture | Backend Mode | Latency (1-min audio) | GPU Load | CPU Load | Speedup |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
+| **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | Vulkan GPU | **360.60 s (6m 00s)** | **949 MHz (100%)** | 20~30% | **2.26x (56% time saved)** |
+| **Galaxy A35** | Cortex-A78 x4 Cores | CPU-NEON | 816.48 s (13m 36s) | 0% | 291% | Baseline |
+
+### 3. Text-to-Speech (Termux-TTS v1.3.0 Vulkan)
+| Target Device | Hardware Architecture | Model Tier | Audio Length | Compute Time | Real-Time Factor (RTF) | Status |
+| :--- | :--- | :--- | :---: | :---: | :---: | :---: |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | `lessac-high-fp16` | 6.70 s | **6.65 s** | **0.993x** | Real-time Studio |
+| **Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | `lessac-medium` | 4.59 s | **1.21 s** | **0.264x** | 3.79x Faster than RT |
+| **Galaxy A35** | Exynos 1380 / Mali-G68 MP5 | `lessac-medium` | 4.52 s | **5.18 s** | **1.146x** | Validated |
+
+---
+
+## Root-Cause Driver Solutions
+
+1. **ARM Mali-G68 Valhall Integer Truncation**: Enforced medium tile matmul kernel dispatch (`loadstride_b = 4 > 0`), permanently eliminating shader zero-stride infinite loops on subgroup-16 hardware.
+2. **Qualcomm Adreno 830 JIT Register Bug**: Bounded vector column specialization (`mul_mat_vec_max_cols = 2`), preventing compiler crash `VK_ERROR_UNKNOWN (-13)`.
+3. **Zero-Silent-Fallback**: Guaranteed fail-fast architecture without silent CPU degradation upon GPU driver faults.
+
+---
+
+## Installation
+
+```bash
+# Python SDK
+pip install ameva-runtime
+
+# Node.js / TypeScript
+npm install @ameva/runtime
+```
+
+---
+
+## Quickstart
+
+### Python SDK
+```python
+import ameva_runtime as ameva
+from ameva_runtime import vulkan
+
+# 1. Inspect on-device silicon topology
+profile = ameva.detect_hardware()
+print(f"SoC: {profile.soc_name} | GPU: {profile.gpu_vendor}")
+
+# 2. Run hardware self-test
+doc = vulkan.Doctor()
+report = doc.run_self_test()
+print(f"GPU: {report.device_name} (Passed: {report.passed_stages}/{report.total_stages})")
+```
+
+### Node.js / TypeScript
+```typescript
+import { Doctor, createContext } from '@ameva/runtime';
+
+const doc = new Doctor();
+const report = await doc.runSelfTest();
+console.log(`Vulkan GPU: ${report.deviceName}`);
+```
+
+---
+
+## Official Documentation & Benchmarks
+- [Official Architecture & API Reference](https://uno-km.vercel.app/lib/vulkan/)
+- [Ecosystem Metrics & Registry Stats](https://uno-km.vercel.app/foundation/metrics)
+- [AMEVA Open-Source Foundation Portal](https://uno-km.vercel.app/foundation/index.html)
+
+---
+
+## License
+Licensed under the Apache-2.0 License. Copyright (c) 2026 Eunho Kim ([@uno-km](https://github.com/uno-km)).

ameva_runtime-2.2.0/README.pypi.md

@@ -0,0 +1,41 @@
+# AMEVA-Runtime (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/ameva-runtime.svg?style=flat-square&color=0369a1)](https://pypi.org/project/ameva-runtime/)
+[![Python](https://img.shields.io/pypi/pyversions/ameva-runtime.svg?style=flat-square)](https://pypi.org/project/ameva-runtime/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-004499.svg?style=flat-square)](https://github.com/uno-km/ameva-runtime)
+
+> Next-Gen Unified On-Device Hardware Orchestration & 6-Modality AI Acceleration Runtime for Mobile & Edge
+
+## Installation
+
+```bash
+pip install ameva-runtime
+```
+
+## Quickstart
+
+```python
+import ameva_runtime as ameva
+from ameva_runtime import vulkan
+
+# Inspect hardware
+profile = ameva.detect_hardware()
+print(f"Target: {profile.soc_name} | {profile.gpu_vendor}")
+
+# Run diagnostics
+doc = vulkan.Doctor()
+report = doc.run_self_test()
+print(f"Passed: {report.passed_stages}/{report.total_stages}")
+```
+
+## Empirical Benchmarks
+
+- **Galaxy S25 (Adreno 830)**: LLM 35.80 t/s (VRAM 25/25 layers), Whisper STT 4,401 ms, TTS RTF 0.264x (medium) / 0.993x (high-fp16).
+- **Galaxy A35 (Mali-G68 MP5)**: LLM 4.44 t/s (+26.9% vs NEON), Whisper STT 360.60s (2.26x speedup), TTS RTF 1.146x.
+
+## Documentation
+- [Official Documentation](https://uno-km.vercel.app/lib/vulkan/)
+- [GitHub Repository](https://github.com/uno-km/ameva-runtime)
+
+## License
+Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).

{ameva_runtime-2.0.2 → ameva_runtime-2.2.0}/pyproject.toml

@@ -40,19 +40,19 @@ Repository = "https://github.com/uno-km/ameva-runtime"
 Documentation = "https://uno-km.vercel.app/lib/vulkan/"
 
 [project.optional-dependencies]
-stt       = ["termux-stt>=1.1.1"]
-diffusion = ["termux-diffusion>=1.3.1"]
-bitnet    = ["termux-bitnet>=1.0.0"]
-llamacpp  = ["termux-llamacpp>=1.0.0"]
-tts       = ["termux-tts>=1.0.0"]
-vision    = ["termux-vision>=1.0.0"]
+stt       = ["termux-stt>=1.2.0"]
+diffusion = ["termux-diffusion>=1.5.0"]
+bitnet    = ["termux-bitnet>=1.2.0"]
+llamacpp  = ["termux-llamacpp>=1.3.0"]
+tts       = ["termux-tts>=1.4.0"]
+vision    = ["termux-vision>=1.2.0"]
 all = [
-    "termux-stt>=1.1.1",
-    "termux-diffusion>=1.3.1",
-    "termux-bitnet>=1.0.0",
-    "termux-llamacpp>=1.0.0",
-    "termux-tts>=1.0.0",
-    "termux-vision>=1.0.0",
+    "termux-stt>=1.2.0",
+    "termux-diffusion>=1.5.0",
+    "termux-bitnet>=1.2.0",
+    "termux-llamacpp>=1.3.0",
+    "termux-tts>=1.4.0",
+    "termux-vision>=1.2.0",
 ]
 
 [tool.pytest.ini_options]

{ameva_runtime-2.0.2 → ameva_runtime-2.2.0}/python/ameva_runtime/_version.py

@@ -5,4 +5,4 @@ Single Source of Truth (SSOT) for all runtime packages.
 Modifying this single string updates ameva_runtime, ameva_runtime.vulkan,
 and the package metadata simultaneously.
 """
-__version__ = "2.0.2"
+__version__ = "2.2.0"

{ameva_runtime-2.0.2/python/ameva_runtime/vulkan → ameva_runtime-2.2.0/python/ameva_runtime}/adapters/__init__.py

@@ -11,7 +11,19 @@ Re-exports individual modality adapters for:
 """
 from __future__ import annotations
 
-from .base import _is_vulkan_report, _make_cpu_fallback, _ADRENO_VENDOR_ID, _MALI_VENDOR_ID, BindingResult, get_vulkan_env, find_system_vulkan_driver_dir
+from .base import (
+    _is_vulkan_report,
+    _make_cpu_fallback,
+    _make_cpu_binding,
+    check_vulkan_availability_or_raise,
+    _ADRENO_VENDOR_ID,
+    _MALI_VENDOR_ID,
+    BindingResult,
+    BaseAdapter,
+    resolve_diagnostic_report,
+    get_vulkan_env,
+    find_system_vulkan_driver_dir,
+)
 from .bitnet import BitnetAdapter
 from .diffusion import DiffusionAdapter
 from .llamacpp import LlamaCppAdapter
@@ -20,6 +32,8 @@ from .tts import TtsAdapter
 from .vision import VisionAdapter
 
 __all__ = [
+    "BaseAdapter",
+    "resolve_diagnostic_report",
     "SttAdapter",
     "DiffusionAdapter",
     "BitnetAdapter",
@@ -31,4 +45,7 @@ __all__ = [
     "find_system_vulkan_driver_dir",
     "_is_vulkan_report",
     "_make_cpu_fallback",
+    "_make_cpu_binding",
+    "check_vulkan_availability_or_raise",
 ]
+

ameva_runtime-2.2.0/python/ameva_runtime/adapters/base.py

@@ -0,0 +1,247 @@
+"""
+Base Utilities & Common Logic for Ameva Modality Adapters
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+try:
+    from ..doctor import DiagnosticReport
+except ImportError:
+    DiagnosticReport = Any
+
+from ameva_runtime.protocol import BindingResult
+
+logger = logging.getLogger("ameva_vulkan_runtime.adapters")
+
+_ADRENO_VENDOR_ID = 0x5143
+_MALI_VENDOR_ID = 0x13B5
+
+
+def resolve_diagnostic_report(report: Any = None, profile: Any = None) -> DiagnosticReport:
+    """Resolves DiagnosticReport from either an existing report, a HardwareProfile, or Doctor auto-probe."""
+    if report is not None:
+        return report
+    if profile is not None:
+        is_vk = (getattr(profile, "recommended_backend", "") == "vulkan" and not getattr(profile, "hardware_hazard", None))
+        gpu_family = getattr(profile, "gpu_family", "generic")
+        return DiagnosticReport(
+            device_name=getattr(profile, "soc_model", None) or gpu_family,
+            vendor_id=_MALI_VENDOR_ID if gpu_family == "mali" else _ADRENO_VENDOR_ID,
+            overall_success=is_vk,
+            recommended_backend=getattr(profile, "recommended_backend", "cpu_neon"),
+            passed_stages=12 if is_vk else 0,
+            total_stages=12,
+            loader_path="/system/lib64/libvulkan.so",
+            hazard=getattr(profile, "hardware_hazard", None),
+            allowed_cpus=sorted(list(getattr(profile, "allowed_cpu_set", []))),
+            diagnosis_reason=getattr(profile, "diagnosis_reason", ""),
+        )
+    try:
+        from ..doctor import Doctor
+        return Doctor().run_diagnostics()
+    except Exception as err:
+        logger.debug("[ameva-runtime:adapters] Doctor probe fallback to minimal report: %s", err)
+        return DiagnosticReport(
+            device_name="Unknown",
+            vendor_id=0,
+            overall_success=False,
+            recommended_backend="cpu_neon",
+            passed_stages=0,
+            total_stages=12,
+        )
+
+
+class BaseAdapter:
+    """Base class for all ameva modality adapters providing common diagnostic helpers."""
+
+    @staticmethod
+    def resolve_diagnostic_report(report: Any = None, profile: Any = None) -> DiagnosticReport:
+        return resolve_diagnostic_report(report, profile)
+
+
+def _is_vulkan_report(report: Optional[DiagnosticReport]) -> bool:
+    if report is None:
+        return False
+    if not report.device_name or report.device_name in ("Unknown", "None", ""):
+        return False
+    return bool(
+        report.overall_success
+        or report.recommended_backend in ("vulkan", "vulkan_driver_only")
+        or report.passed_stages >= 7
+    )
+
+
+def check_vulkan_availability_or_raise(
+    module: str,
+    report: Any,
+    is_vk: bool,
+    requested_backend: Optional[str] = None,
+) -> None:
+    """Enforces Fail-Fast: If Vulkan was explicitly requested but is unavailable, raise PlatformNotSupportedError."""
+    if requested_backend == "vulkan" and not is_vk:
+        device = getattr(report, "device_name", None) or "Unknown"
+        diag_reason = getattr(report, "diagnosis_reason", None) or "Vulkan ICD / driver missing or self-test validation failed"
+        from ..exceptions import PlatformNotSupportedError
+        raise PlatformNotSupportedError(
+            f"[{module}] Vulkan acceleration backend explicitly requested, but no valid Vulkan driver/environment is available.\n"
+            f"Target Device: {device}\n"
+            f"Failure Cause: {diag_reason}\n"
+            f"Remediation: Verify Vulkan driver installation or explicitly specify '--device cpu'."
+        )
+
+
+def _make_cpu_binding(
+    module: str,
+    report: DiagnosticReport,
+    config: dict,
+    reason: str = "",
+) -> BindingResult:
+    """Creates a standardized CPU NEON BindingResult when CPU backend is explicitly requested or routed."""
+    device = getattr(report, "device_name", None) or "Generic CPU"
+    msg = f"[ameva-runtime:{module}] Binding CPU NEON backend (Device: {device}"
+    if reason:
+        msg += f", Reason: {reason}"
+    msg += ")"
+    logger.info(msg)
+    config["backend"] = "cpu_neon"
+    return BindingResult(
+        module=module,
+        backend="cpu_neon",
+        is_vulkan=False,
+        device_name=getattr(report, "device_name", "CPU"),
+        vendor_id=getattr(report, "vendor_id", 0),
+        config=config,
+        status="BOUND_CPU_NEON",
+    )
+
+
+# Backward compatibility alias
+_make_cpu_fallback = _make_cpu_binding
+
+
+def _get_optimal_threads() -> int:
+    """Returns optimal threads count for big/performance cores."""
+    import os
+    cpu_count = os.cpu_count() or 8
+    return max(1, min(4, cpu_count // 2 if cpu_count > 4 else cpu_count))
+
+
+def find_system_vulkan_driver_dir() -> Optional[str]:
+    """
+    Dynamically probes and returns the absolute directory path of the valid libvulkan.so driver installed on the system.
+    Tier 1: Directly inspect /proc/self/maps Linux kernel virtual memory mapping (Ground Truth, 0% root required).
+    Tier 2: Probe standard 64-bit / 32-bit Android HAL directories.
+    """
+    import sys
+    import os
+    import ctypes
+    from pathlib import Path
+
+    # Tier 1: Linux kernel process virtual memory map inspection (Ground Truth)
+    try:
+        handle = ctypes.CDLL("libvulkan.so")
+        if hasattr(handle, "vkCreateInstance"):
+            maps_path = Path("/proc/self/maps")
+            if maps_path.is_file():
+                with open(maps_path, "r", encoding="utf-8", errors="ignore") as f:
+                    for line in f:
+                        if "libvulkan.so" in line:
+                            parts = line.strip().split()
+                            if len(parts) >= 6:
+                                real_path = parts[-1]
+                                if os.path.isabs(real_path) and os.path.exists(real_path):
+                                    return str(Path(real_path).parent.resolve())
+    except Exception:
+        pass
+
+    # Tier 2: Search standard 64-bit vs 32-bit Android HAL directories
+    is_64bit = sys.maxsize > 2**32
+
+    if is_64bit:
+        candidate_dirs = [
+            Path("/system/lib64"),
+            Path("/vendor/lib64"),
+            Path("/apex/com.android.runtime/lib64"),
+            Path("/system/vendor/lib64"),
+        ]
+    else:
+        candidate_dirs = [
+            Path("/system/lib"),
+            Path("/vendor/lib"),
+            Path("/apex/com.android.runtime/lib"),
+            Path("/system/vendor/lib"),
+        ]
+
+    for root in candidate_dirs:
+        so_path = root / "libvulkan.so"
+        if so_path.is_file():
+            try:
+                h = ctypes.CDLL(str(so_path))
+                if hasattr(h, "vkCreateInstance"):
+                    return str(root.resolve())
+            except Exception:
+                continue
+
+    # Tier 3: Simple file existence probe
+    for root in candidate_dirs:
+        if (root / "libvulkan.so").is_file():
+            return str(root.resolve())
+
+    return None
+
+
+def get_vulkan_env(base_env: Optional[dict[str, str]] = None) -> dict[str, str]:
+    """
+    Returns environment variable dictionary for the AMEVA Vulkan runtime.
+    Golden Link Order:
+    1: System Vulkan driver directory (/system/lib64)
+    2: Termux native C++ runtime (/data/data/com.termux/files/usr/lib)
+    3: Bundled runtime library (~/.termux-llama/current/lib)
+    4: Existing system and user environment paths
+    """
+    import os
+    from pathlib import Path
+
+    env = dict(base_env or os.environ)
+    current_ld = env.get("LD_LIBRARY_PATH", "")
+
+    # Dynamically probe verified Vulkan driver directory
+    discovered_driver_dir = find_system_vulkan_driver_dir()
+
+    ordered_dirs = []
+
+    # Priority 1: Smartphone system Vulkan driver directory (/system/lib64)
+    # Prevents Android 15 Bionic libunwindstack symbol collision (system liblzma binds first)
+    if discovered_driver_dir and discovered_driver_dir not in ordered_dirs:
+        ordered_dirs.append(discovered_driver_dir)
+    elif os.path.isdir("/system/lib64") and "/system/lib64" not in ordered_dirs:
+        ordered_dirs.append("/system/lib64")
+
+    # Priority 2: Termux native C++ runtime
+    termux_usr_lib = "/data/data/com.termux/files/usr/lib"
+    if os.path.isdir(termux_usr_lib) and termux_usr_lib not in ordered_dirs:
+        ordered_dirs.append(termux_usr_lib)
+
+    # Priority 3: Bundled llama/runtime libraries
+    llama_lib = str(Path.home() / ".termux-llama/current/lib")
+    if os.path.isdir(llama_lib) and llama_lib not in ordered_dirs:
+        ordered_dirs.append(llama_lib)
+
+    # Priority 4: Append remaining paths without duplication
+    existing_parts = [p for p in current_ld.split(":") if p]
+    final_dirs = ordered_dirs + [p for p in existing_parts if p not in ordered_dirs]
+    env["LD_LIBRARY_PATH"] = ":".join(final_dirs)
+
+    # Mali GPU Quirks: Avoid infinite GEMM quantization loops on ARM Mali Valhall architectures
+    try:
+        from ..platform import detect_soc_environment
+        soc = detect_soc_environment()
+        if "mali" in str(soc.gpu_family).lower() or soc.vendor == "samsung":
+            env.setdefault("GGML_VK_FORCE_MEDIUM_MATMUL", "1")
+            env.setdefault("GGML_VK_DISABLE_F16", "1")
+    except Exception:
+        pass
+
+    return env