Metadata-Version: 2.4
Name: ameva-runtime
Version: 1.0.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.1.1; extra == "stt"
Provides-Extra: diffusion
Requires-Dist: termux-diffusion>=1.3.1; extra == "diffusion"
Provides-Extra: bitnet
Requires-Dist: termux-bitnet>=1.0.0; extra == "bitnet"
Provides-Extra: llamacpp
Requires-Dist: termux-llamacpp>=1.0.0; extra == "llamacpp"
Provides-Extra: tts
Requires-Dist: termux-tts>=1.0.0; extra == "tts"
Provides-Extra: vision
Requires-Dist: termux-vision>=1.0.0; extra == "vision"
Provides-Extra: all
Requires-Dist: termux-stt>=1.1.1; extra == "all"
Requires-Dist: termux-diffusion>=1.3.1; extra == "all"
Requires-Dist: termux-bitnet>=1.0.0; extra == "all"
Requires-Dist: termux-llamacpp>=1.0.0; extra == "all"
Requires-Dist: termux-tts>=1.0.0; extra == "all"
Requires-Dist: termux-vision>=1.0.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 & Multi-Modal Acceleration Runtime for Mobile & Edge*

## Installation

```bash
pip install ameva-runtime
```

## Quickstart

```python
import ameva_runtime as ameva

# 1. Execute LLM inference directly with optimal on-device hardware dispatch
result = ameva.run(
    model="qwen2.5-0.5b",
    prompt="Space in Korean is:",
    max_tokens=32
)

print(f"Generated text: {result.text}")
print(f"Hardware backend: {result.backend_used} ({result.tokens_per_second:.2f} t/s)")

# 2. Preview hardware execution plan
plan = ameva.plan(model="qwen2.5-0.5b")
print(f"Route: {plan.backend} | NGL: {plan.ngl} | Threads: {plan.threads}")

```

## Description
AMEVA Runtime provides a unified, zero-silent-fallback hardware orchestration engine for generative AI on mobile and edge devices. It automatically resolves vendor divergence, dispatching to native Vulkan hardware offload on Qualcomm Adreno while isolating driver deadlocks on ARM Mali through deterministic Cortex-A78 CPU-NEON multi-threading.

### Empirical Hardware Benchmarks (Qwen2.5-0.5B-Instruct)

| Device & SoC | GPU & Driver Architecture | Backend Route | Layer Offload | Generation Speed | Prompt Eval Speed | UI Freeze | Speedup |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Galaxy S25** (Snapdragon 8 Elite) | Qualcomm Adreno 830 (Vulkan 1.3) | **VULKAN** | **25/25 (100% VRAM)** | **35.80 t/s** (27.93 ms/t) | **4.53 t/s** | **0%** | **35.8x** |
| **Galaxy A35** (Exynos 1380) | ARM Mali-G68 MP5 (Vulkan 1.3) | **CPU-NEON** | **0/25 (Safe Guard)** | **3.55 t/s** (295 ms/t) | **8.05 t/s** | **0%** | Baseline |
| **Galaxy A35** (Forced Vulkan Test) | ARM Mali-G68 MP5 (vulkan.mali.so) | VULKAN | 25/25 | 0.00 t/s (Deadlock) | - | 100% (Hung) | Failed |

### Technical Rationale for ARM Mali CPU-NEON Fallback
The proprietary ARM Mali Vulkan driver (`/vendor/lib64/hw/vulkan.mali.so` via `/dev/mali0`) enforces aggressive kernel-level dynamic power management (DVFS) tied to `SurfaceFlinger` display composition. During headless compute dispatches in terminal or CLI environments (lacking an active window swapchain), the Mali driver interprets the absence of display flips as an idle state, downclocking GPU compute cores and failing to signal in-flight completion fences. This causes host threads waiting on `vkWaitForFences` or `vkQueueWaitIdle` to deadlock indefinitely.

To guarantee rock-solid system stability and eliminate device lockups, the **AMEVA SmartRouter** automatically identifies ARM Mali GPUs, bypasses the unstable headless Vulkan path, and dispatches inference to the high-performance ARM Cortex-A78 CPU-NEON cluster.

### CLI Quickstart
```bash
# 1. Automatic hardware diagnosis and profile inspection
ameva-run doctor
ameva-run profile

# 2. Dry-run execution plan
ameva-run plan -m qwen2.5-0.5b

# 3. Direct model execution with automatic hardware acceleration
ameva-run exec -m qwen2.5-0.5b -p "Space in Korean is:" -n 32
```


## Documentation
- [Official Documentation & API Reference](https://uno-km.vercel.app/lib/ameva-vulkan-runtime/)
- [GitHub Repository](https://github.com/uno-km/ameva-runtime)

## License
Apache-2.0 License. Copyright (c) 2026 Eunho Kim (@uno-km).
