termux-vision 1.3.1 → 1.4.1

package/README.md

@@ -60,8 +60,8 @@ pkg install -y python nodejs clang make cmake git termux-api wget vulkan-loader
 
 * **Option B: Direct GitHub Releases Wheel Asset (SSOT Verified)**:
   ```bash
-  # Download and install the prebuilt v1.3.1 release wheel
-  pip install https://github.com/uno-km/termux-vision/releases/download/v1.3.1/termux_vision-1.3.1-py3-none-any.whl
+  # Download and install the prebuilt v1.4.1 release wheel
+  pip install https://github.com/uno-km/termux-vision/releases/download/v1.4.1/termux_vision-1.4.1-py3-none-any.whl
   ```
 
 ### 2.3 Node.js / TypeScript CLI Installation
@@ -98,8 +98,8 @@ npm install -g termux-vision @ameva/runtime
 
 | GPU Microarchitecture | Silicon / SoC Reference | Status | Optimization Mechanics |
 | :--- | :--- | :--- | :--- |
+| **Qualcomm Adreno GPU** | Snapdragon 8 Elite (Adreno 830)<br>Snapdragon 8 Gen 1/2/3 (Adreno 730-750) | 🟢 **Production Verified** | Direct Bionic ICD binding, SPIR-V JIT patch (`mul_mat_vec_max_cols = 2`), KGSL Watchdog defense (`GGML_VULKAN_SKIP_CHECKS="999999999"`), micro-batch prefill chunking (`-b 64 -ub 64`). |
 | **ARM Mali GPU** | Exynos 2100 (Mali-G78 MP14)<br>Exynos 1380 (Mali-G68 MP5) | 🟢 **Production Verified** | Bionic Vulkan ICD binding, Tile-Based Deferred Rendering (TBDR) memory isolation, MMVQ matrix-vector kernel dispatch (`--tune-mali`). |
-| **Qualcomm Adreno GPU** | Snapdragon 8 Gen 1/2/3/Elite<br>(Adreno 730 / 740 / 750 / 830) | 🟡 **In Development (개발 진행 중)** | Direct Bionic ICD & Freedreno/Turnip dispatch layers under active engineering. |
 | **Samsung Xclipse GPU** | Exynos 2200 / 2400<br>(Xclipse 920 / 940 - AMD RDNA) | 🟡 **In Development (개발 진행 중)** | SPIR-V instruction scheduling and RDNA mobile shader alignment under active engineering. |
 
 Verify GPU driver detection and hardware readiness:
@@ -223,19 +223,48 @@ termux-vision doctor
 
 ## 7. Real-World Benchmarks & Hardware Scorecard
 
-All metrics represent deterministic ground-truth measurements obtained on physical test devices running Android Termux unrooted, using SmolVLM-500M Instruct (Q4_K_M text model + Q8_0 mmproj vision projector).
-
-| Target Device | SoC / GPU Architecture | Mode | Input Resolution | Prompt Eval | Token Generation | Total Latency | CPU Mapped VRAM | Vulkan GPU VRAM | Generation Speedup |
-| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| **Samsung Galaxy S21 5G** | Exynos 2100<br>ARM Mali-G78 MP14 | **GPU (Vulkan)** | 224x224 | **14.28 tok/s** | **12.65 tok/s** | **21.26 s** | **0.00 MiB** | **1059.02 MiB** | **+58.9%** |
-| Samsung Galaxy S21 5G | Exynos 2100<br>8-Core ARMv8.2-A CPU | CPU (NEON) | 224x224 | 8.84 tok/s | 7.96 tok/s | 34.22 s | 1059.02 MiB | 0.00 MiB | Baseline |
-| **Samsung Galaxy A35 5G** | Exynos 1380<br>ARM Mali-G68 MP5 | **GPU (Vulkan)** | 224x224 | **5.67 tok/s** | **5.47 tok/s** | **52.57 s** | **0.00 MiB** | **1059.02 MiB** | **+55.8%** |
-| Samsung Galaxy A35 5G | Exynos 1380<br>8-Core ARMv8.2-A CPU | CPU (NEON) | 224x224 | 4.88 tok/s | 3.51 tok/s | 65.34 s | 1059.02 MiB | 0.00 MiB | Baseline |
-
-### Key Performance Discoveries
-1. **100% Elimination of CPU Mapped VRAM**: In GPU mode (`-d gpu`), CPU mapped model buffer is completely zeroed out (`0.00 MiB`), offloading all 1059.02 MiB of model tensor data and 384.00 MiB of KV cache into Vulkan GPU buffers.
-2. **TBDR Tile Cache Synergy**: ARM Mali-G78 delivers a **+58.9%** throughput increase over pure CPU SIMD, maintaining thermal stability under continuous mobile inference.
-3. **Consistent Sub-Device Scaling**: Galaxy A35 (Mali-G68 5-core) achieves consistent ~5.5 tok/s generation throughput, proving robust multi-tier edge scalability.
+All metrics represent deterministic ground-truth measurements obtained on physical test devices running Android Termux unrooted, comparing **Moondream2 1.8B f16** and **SmolVLM-500M Instruct (Q4_K_M + Q8_0 mmproj)**.
+
+| Target Device | SoC & GPU Architecture | Model Architecture | Precision & Weights | Mode | Prompt Processing | Token Generation | Total Latency | Mapped CPU VRAM | Vulkan GPU VRAM | Status / Speedup |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **Samsung Galaxy S25** | Snapdragon 8 Elite<br>Qualcomm Adreno 830 | **Moondream2 1.8B** | Text f16 (2.7GB)<br>+ ViT f16 (868MB) | **GPU (Vulkan 25/25)** | **19.84 tok/s** | **15.00 tok/s** | **39.20 s** | **0.00 MiB** | **2,706.00 MiB** | **Production Verified** |
+| **Samsung Galaxy S21 5G** | Exynos 2100<br>ARM Mali-G78 MP14 | SmolVLM-500M-Instruct | Q4_K_M (350MB)<br>+ Q8_0 mmproj (200MB) | **GPU (Vulkan)** | **14.28 tok/s** | **12.65 tok/s** | **21.26 s** | **0.00 MiB** | **1,059.02 MiB** | **+58.9% vs CPU** |
+| Samsung Galaxy S21 5G | Exynos 2100<br>8-Core ARMv8.2-A CPU | SmolVLM-500M-Instruct | Q4_K_M (350MB)<br>+ Q8_0 mmproj (200MB) | CPU (NEON) | 8.84 tok/s | 7.96 tok/s | 34.22 s | 1,059.02 MiB | 0.00 MiB | Baseline |
+| **Samsung Galaxy A35 5G** | Exynos 1380<br>ARM Mali-G68 MP5 | SmolVLM-500M-Instruct | Q4_K_M (350MB)<br>+ Q8_0 mmproj (200MB) | **GPU (Vulkan)** | **5.67 tok/s** | **5.47 tok/s** | **52.57 s** | **0.00 MiB** | **1,059.02 MiB** | **+55.8% vs CPU** |
+| Samsung Galaxy A35 5G | Exynos 1380<br>8-Core ARMv8.2-A CPU | SmolVLM-500M-Instruct | Q4_K_M (350MB)<br>+ Q8_0 mmproj (200MB) | CPU (NEON) | 4.88 tok/s | 3.51 tok/s | 65.34 s | 1,059.02 MiB | 0.00 MiB | Baseline |
+
+### 7.1 Empirical Visual Question Answering Verification (Galaxy S25 Adreno 830)
+
+#### Test Case A: Geometric & Spatial Reasoning (`test_shapes_224x224.png`)
+* **Input Image**: Clean canvas with primary geometric primitives (triangles, rectangle).
+* **Prompt**: `"Describe the colors and geometric shapes visible in this image."`
+* **Model**: `Moondream2 1.8B` (f16 text + f16 ViT mmproj, 2,706 MiB VRAM)
+* **Exact Ground-Truth Output**:
+  > *"The image features a white background with three distinct geometric shapes: two triangles and one rectangle..."*
+* **Execution Metrics**:
+  - GPU Layers Offloaded: **25 / 25 (100% Full GPU)**
+  - Vulkan VRAM Allocated: **2,706.00 MiB** (CPU Mapped VRAM: **0.00 MiB**)
+  - Prompt Evaluation: **19.60 tokens/sec** (749 tokens in 38,211 ms)
+  - Token Generation: **14.97 tokens/sec** (39 tokens in 2,605 ms, 66.80 ms/tok)
+  - Total Execution Time: **51.24s** (Cold weights loading: 10.4s, CPU ViT projection: 14.1s, GPU decoding: 2.6s)
+  - Exit Status: `Exit Code 0`
+
+#### Test Case B: Photorealistic Real-World Scene (`test_elephant_gpu_step2.png`)
+* **Input Image**: Diffusion-synthesized high-detail photorealistic scene.
+* **Prompt**: `"What animal is this and what is it doing?"`
+* **Model**: `Moondream2 1.8B` (f16 text + f16 ViT mmproj)
+* **Exact Ground-Truth Output**:
+  > *"The image shows a large elephant riding on top of a surfboard in the ocean."*
+* **Execution Metrics**:
+  - Prompt Processing: **19.84 tokens/sec** (747 tokens in 37,651 ms)
+  - Generation Speed: **15.00 tokens/sec** (24 tokens in 1,600 ms, 66.67 ms/tok)
+  - KGSL Watchdog State: Fully stabilized via `GGML_VULKAN_SKIP_CHECKS="999999999"` (No `ErrorDeviceLost`)
+  - Exit Status: `Exit Code 0`
+
+### 7.2 Key Architectural Discoveries
+1. **Adreno 830 SPIR-V JIT Fix**: Qualcomm's new compiler fails during unrolled vector compilation with `mul_mat_vec_max_cols = 8` (`VK_ERROR_UNKNOWN`). Reducing this parameter to `2` eliminates register spilling and enables full 25/25 layer GPU offloading.
+2. **Android KGSL Watchdog Defense**: Prefilling 729 vision tokens in mobile Vulkan exceeds the 5-second kernel watchdog timer unless micro-batched. Configuring `-b 64 -ub 64` and injecting `GGML_VULKAN_SKIP_CHECKS="999999999"` slices prefill into 1.8s units, preventing `ErrorDeviceLost`.
+3. **Pure GPU Isolation (0.00 MiB CPU VRAM)**: Across both Qualcomm Adreno 830 and ARM Mali (G78/G68), all tensor weights and KV cache reside strictly in Vulkan GPU memory.
 
 ---
 

package/README.pypi.md

@@ -31,7 +31,7 @@ pip install termux-vision
 
 ### 2.2 Direct GitHub Releases Wheel Asset
 ```bash
-pip install https://github.com/uno-km/termux-vision/releases/download/v1.3.1/termux_vision-1.3.1-py3-none-any.whl
+pip install https://github.com/uno-km/termux-vision/releases/download/v1.4.1/termux_vision-1.4.1-py3-none-any.whl
 ```
 
 ### 2.3 One-Line Bootstrap Installer
@@ -48,9 +48,9 @@ pip install termux-vision ameva-runtime termux-llamacpp
 ```
 
 ### Silicon Architecture Support Status
+* **Qualcomm Adreno GPU (Snapdragon 8 Elite / Adreno 830, Adreno 7xx)**: Production Verified & Supported (Full 25/25 layer GPU offloading, 15.00 tok/s on Moondream2 1.8B f16, SPIR-V JIT patch, KGSL watchdog defense via `GGML_VULKAN_SKIP_CHECKS="999999999"`).
 * **ARM Mali GPU (Mali-G78, Mali-G68, etc.)**: Production Verified & Supported (Pure GPU offloading, 0.00 MiB CPU Mapped VRAM, MMVQ tuning via `--tune-mali`).
-* **Qualcomm Adreno GPU (Adreno 730 / 740 / 750 / 830)**: Under Active Development (In Progress / 개발 진행 중).
-* **Samsung Xclipse GPU (Xclipse 920 / 940 - AMD RDNA)**: Under Active Development (In Progress / 개발 진행 중).
+* **Samsung Xclipse GPU (Xclipse 920 / 940 - AMD RDNA)**: Under Active Engineering (In Progress / 개발 진행 중).
 
 Run hardware diagnostics:
 ```bash
@@ -105,14 +105,15 @@ with tv.vlm.load("smolvlm-500m", device="gpu") as engine:
 
 ---
 
-## 6. Real-World Benchmarks (SmolVLM-500M)
+## 6. Real-World Benchmarks & Hardware Scorecard
 
-| Target Device | SoC / GPU | Mode | Prompt Eval | Token Generation | CPU Mapped VRAM | GPU VRAM | Speedup |
-| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
-| **Samsung Galaxy S21 5G** | Exynos 2100 / Mali-G78 | **GPU (Vulkan)** | **14.28 tok/s** | **12.65 tok/s** | **0.00 MiB** | **1059.02 MiB** | **+58.9%** |
-| Samsung Galaxy S21 5G | Exynos 2100 / 8-Core CPU | CPU (NEON) | 8.84 tok/s | 7.96 tok/s | 1059.02 MiB | 0.00 MiB | Baseline |
-| **Samsung Galaxy A35 5G** | Exynos 1380 / Mali-G68 | **GPU (Vulkan)** | **5.67 tok/s** | **5.47 tok/s** | **0.00 MiB** | **1059.02 MiB** | **+55.8%** |
-| Samsung Galaxy A35 5G | Exynos 1380 / 8-Core CPU | CPU (NEON) | 4.88 tok/s | 3.51 tok/s | 1059.02 MiB | 0.00 MiB | Baseline |
+| Target Device | SoC & GPU | Model Architecture | Mode | Prompt Processing | Token Generation | Mapped CPU VRAM | Vulkan GPU VRAM | Status / Speedup |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| **Samsung Galaxy S25** | Snapdragon 8 Elite / Adreno 830 | **Moondream2 1.8B f16** | **GPU (Vulkan 25/25)** | **19.84 tok/s** | **15.00 tok/s** | **0.00 MiB** | **2,706.00 MiB** | **Verified (Full GPU)** |
+| **Samsung Galaxy S21 5G** | Exynos 2100 / Mali-G78 | SmolVLM-500M-Instruct | **GPU (Vulkan)** | **14.28 tok/s** | **12.65 tok/s** | **0.00 MiB** | **1,059.02 MiB** | **+58.9% vs CPU** |
+| Samsung Galaxy S21 5G | Exynos 2100 / 8-Core CPU | SmolVLM-500M-Instruct | CPU (NEON) | 8.84 tok/s | 7.96 tok/s | 1,059.02 MiB | 0.00 MiB | Baseline |
+| **Samsung Galaxy A35 5G** | Exynos 1380 / Mali-G68 | SmolVLM-500M-Instruct | **GPU (Vulkan)** | **5.67 tok/s** | **5.47 tok/s** | **0.00 MiB** | **1,059.02 MiB** | **+55.8% vs CPU** |
+| Samsung Galaxy A35 5G | Exynos 1380 / 8-Core CPU | SmolVLM-500M-Instruct | CPU (NEON) | 4.88 tok/s | 3.51 tok/s | 1,059.02 MiB | 0.00 MiB | Baseline |
 
 ---
 

package/bin/cli.js

@@ -1,387 +1,51 @@
 #!/usr/bin/env node
-
 /**
- * termux-vision: Node.js Global CLI Binary.
- * High-performance on-device Computer Vision & VLM Multimodal Framework.
- * Open-Source under Apache License 2.0.
+ * AMEVA Standard Node.js CLI Runner for termux_vision.
+ * Automatically resolves Python 3 environment and dispatches to python -m termux_vision.
  */
-
-'use strict';
-
 const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const readline = require('readline');
-
-const { version } = require('../package.json');
-const { runDoctor } = require('../lib/doctor');
-const { ModelCacheManager, CATALOG } = require('../lib/cache');
-const { load } = require('../lib/vlm');
-const { canny } = require('../lib/cv');
-const {
-  ModelNotFoundError,
-  NoInstalledModelsError,
-  ModelSelectionRequiredError,
-  VulkanNotAvailableError,
-  RuntimeNotFoundError,
-  ModelDownloadError
-} = require('../lib/errors');
-
-const args = process.argv.slice(2);
-const command = args[0] || '--help';
+const { spawn, execSync } = require('child_process');
 
-function getArg(flag, alias = null) {
-  let idx = args.indexOf(flag);
-  if (idx === -1 && alias) idx = args.indexOf(alias);
-  return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
-}
-
-function hasFlag(flag, alias = null) {
-  return args.includes(flag) || (alias && args.includes(alias));
-}
-
-function printHelp() {
-  console.log(`termux-vision CLI v${version} (Node.js Engine)`);
-  console.log('Usage: termux-vision <command> [options]\n');
-  console.log('Commands:');
-  console.log('  doctor                           Inspect device hardware, RAM, and Vulkan GPU');
-  console.log('  model list                       List installed VLM models');
-  console.log('  model install <model_id>         Download and install official VLM model');
-  console.log('  model download <url_or_repo>     Freely download model from Hugging Face or direct URL');
-  console.log('  model remove <model_id>          Remove model from cache');
-  console.log('  vlm <image_path> [options]       Execute multimodal image description/chat');
-  console.log('  canny <image_path> [options]     Run Canny edge detection');
-  console.log('  benchmark                        Run on-device vision latency benchmark\n');
-  console.log('Options for VLM:');
-  console.log('  -p, --prompt <text>              Prompt query');
-  console.log('  -m, --model <model_id_or_path>   Model ID or direct path to .gguf file');
-  console.log('  --mmproj <path>                  Vision projector path (mmproj-*.gguf)');
-  console.log('  --device <auto|cpu|vulkan|gpu>   Device backend (auto: Vulkan with CPU fallback; gpu: strict Vulkan)');
-  console.log('  --runtime <path>                 Explicit path to llama-cli executable');
-  console.log('  --allow-download                 Automatically download model if missing');
-  console.log('  -t, --threads <num>              Inference threads (default: 4)');
-  console.log('  -n, --max-tokens <num>           Maximum generated tokens (default: 150)');
-  console.log('  --temp, --temperature <val>      Sampling temperature (default: 0.2)');
-  console.log('  --top-p <val>                    Top-p nucleus sampling');
-  console.log('  --top-k <num>                    Top-k sampling threshold');
-  console.log('  --repeat-penalty <val>           Repetition penalty (default: 1.2)');
-  console.log('  --seed <num>                     Random RNG seed');
-  console.log('  --system-prompt <text>           System prompt context');
-  console.log('  --ngl <num>                      Number of GPU offload layers');
-  console.log('  --json                           Output full metrics in JSON format');
-}
-
-async function promptUser(question) {
-  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
-  return new Promise((resolve) => {
-    rl.question(question, (ans) => {
-      rl.close();
-      resolve(ans.trim().toLowerCase());
-    });
-  });
-}
-
-async function main() {
-  if (hasFlag('-v') || hasFlag('--version')) {
-    console.log(`termux-vision ${version}`);
-    process.exit(0);
+function findPython() {
+  if (process.env.PYTHON && fs.existsSync(process.env.PYTHON)) {
+    return process.env.PYTHON;
   }
-
-  if (command === '--help' || command === '-h' || command === 'help') {
-    printHelp();
-    process.exit(0);
+  const termuxBin = '/data/data/com.termux/files/usr/bin/python3';
+  if (fs.existsSync(termuxBin)) {
+    return termuxBin;
   }
-
-  const cache = new ModelCacheManager();
-
-  if (command === 'doctor') {
-    const probeVulkan = hasFlag('--probe-vulkan');
-    const isJson = hasFlag('--json');
-    const rep = runDoctor(probeVulkan);
-
-    if (isJson) {
-      console.log(JSON.stringify(rep, null, 2));
-    } else {
-      console.log('=== termux-vision Diagnostic Doctor (Node.js Engine) ===');
-      console.log(`  Platform : ${rep.platform.system} (${rep.platform.machine}) | Android: ${rep.platform.isAndroid}`);
-      console.log(`  RAM      : Total ${rep.hardware.totalRamMb}MB | Available ${rep.hardware.availableRamMb}MB`);
-      console.log(`  CPU Cores: ${rep.hardware.cpuCores}`);
-      console.log(`  Vulkan   : Loader=${rep.vulkan.loaderDetected} | Driver=${rep.vulkan.driverDetected} | Status=${rep.vulkan.status}`);
-      console.log(`  Models   : ${rep.vlmRuntime.installedModelsCount} installed in ${rep.vlmRuntime.cacheDir}`);
-      console.log(`  Preset   : ${rep.recommendedPreset}`);
-    }
-    process.exit(0);
-  }
-
-  if (command === 'model') {
-    const action = args[1] || 'list';
-    if (action === 'list') {
-      const isJson = hasFlag('--json');
-      const installed = cache.listInstalled();
-      if (isJson) {
-        console.log(JSON.stringify(installed, null, 2));
-      } else {
-        console.log(`=== Installed VLM Models (${installed.length}) ===`);
-        if (installed.length === 0) {
-          console.log('  (none in ~/.cache/termux-vision/models)');
-        } else {
-          for (const m of installed) {
-            console.log(`  - ${m.modelId.padEnd(20)} | Tier: ${m.tier} | State: ${m.state} | Size: ${m.sizeMb}MB`);
-          }
-        }
-        console.log('\nAvailable Official Presets:');
-        for (const [k, v] of Object.entries(CATALOG)) {
-          console.log(`  * ${k.padEnd(20)} | Tier: ${v.tier} | Est. RAM: ${v.estimatedMemoryMb}MB`);
-        }
-      }
-      process.exit(0);
-    }
-
-    if (action === 'install') {
-      const modelId = args[2];
-      if (!modelId) {
-        console.error('[ERROR] Please specify a model ID to install (e.g. smolvlm-500m-q4).');
-        process.exit(2);
-      }
-      console.log(`[*] Installing model: ${modelId}...`);
-      try {
-        await cache.install(modelId, (fname, downloaded, total) => {
-          const pct = total > 0 ? (downloaded / total * 100).toFixed(1) : '0.0';
-          process.stdout.write(`\r  Downloading ${fname}: ${(downloaded / 1048576).toFixed(1)}/${(total / 1048576).toFixed(1)}MB (${pct}%)`);
-        });
-        console.log(`\n[+] Successfully installed '${modelId}'.`);
-        process.exit(0);
-      } catch (err) {
-        console.error(`\n[-] Model installation failed: ${err.message}`);
-        process.exit(11);
-      }
-    }
-
-    if (action === 'download') {
-      const source = args[2];
-      if (!source) {
-        console.error('[ERROR] Please provide a Hugging Face repo or direct URL.');
-        process.exit(2);
-      }
-      const outDir = getArg('-o', '--output') || cache.modelsDir;
-      console.log(`[*] Downloading model from: ${source}...`);
-      try {
-        let dest = path.join(outDir, path.basename(source.split('?')[0]));
-        if (source.startsWith('hf:') || source.includes(':')) {
-          const parts = (source.startsWith('hf:') ? source.slice(3) : source).split(':');
-          if (parts.length === 2) {
-            const url = `https://huggingface.co/${parts[0].trim()}/resolve/main/${parts[1].trim()}`;
-            dest = path.join(outDir, parts[1].trim());
-            await cache.downloadFile(url, dest, (fname, d, t) => {
-              const pct = t > 0 ? (d / t * 100).toFixed(1) : '0.0';
-              process.stdout.write(`\r  Downloading ${fname}: ${(d / 1048576).toFixed(1)}/${(t / 1048576).toFixed(1)}MB (${pct}%)`);
-            });
-          }
-        } else if (source.startsWith('http')) {
-          await cache.downloadFile(source, dest, (fname, d, t) => {
-            const pct = t > 0 ? (d / t * 100).toFixed(1) : '0.0';
-            process.stdout.write(`\r  Downloading ${fname}: ${(d / 1048576).toFixed(1)}/${(t / 1048576).toFixed(1)}MB (${pct}%)`);
-          });
-        }
-        console.log(`\n[+] Model downloaded successfully to: ${dest}`);
-        process.exit(0);
-      } catch (err) {
-        console.error(`\n[-] Model download failed: ${err.message}`);
-        process.exit(11);
-      }
-    }
-
-    if (action === 'remove') {
-      const modelId = args[2];
-      if (!modelId) {
-        console.error('[ERROR] Please specify a model ID to remove.');
-        process.exit(2);
-      }
-      if (cache.remove(modelId)) {
-        console.log(`[+] Model '${modelId}' removed from cache.`);
-        process.exit(0);
-      } else {
-        console.error(`[-] Model '${modelId}' was not found in cache.`);
-        process.exit(10);
-      }
-    }
+  const termuxBinAlt = '/data/data/com.termux/files/usr/bin/python';
+  if (fs.existsSync(termuxBinAlt)) {
+    return termuxBinAlt;
   }
-
-  if (command === 'vlm') {
-    const imagePath = args[1];
-    if (!imagePath || imagePath.startsWith('-')) {
-      console.error('[ERROR] Missing input image path for VLM inference.');
-      console.error('Usage: termux-vision vlm <image_path> [options]');
-      process.exit(2);
-    }
-
-    const prompt = getArg('-p', '--prompt');
-    const model = getArg('-m', '--model');
-    const mmproj = getArg('--mmproj', null);
-    const device = getArg('--device', null) || 'auto';
-    const runtime = getArg('--runtime', null);
-    const allowDownload = hasFlag('--allow-download');
-    const threads = getArg('-t', '--threads');
-    const maxTokens = getArg('-n', '--max-tokens');
-    const temp = getArg('--temp', '--temperature');
-    const topP = getArg('--top-p', null);
-    const topK = getArg('--top-k', null);
-    const repeatPenalty = getArg('--repeat-penalty', null);
-    const seed = getArg('--seed', null);
-    const systemPrompt = getArg('--system-prompt', null);
-    const ctxSize = getArg('-c', '--ctx-size');
-    const quality = getArg('-q', '--quality') || 'optimal';
-    const maxDim = getArg('--max-dim', null);
-    const ngl = getArg('--ngl', null);
-    const isJson = hasFlag('--json');
-
+  const candidates = ['python3', 'python'];
+  for (const cmd of candidates) {
     try {
-      let targetModel = model;
-      if (!targetModel) {
-        const installed = cache.listInstalled();
-        if (installed.length === 0) {
-          if (allowDownload) {
-            targetModel = 'smolvlm-500m-q4';
-          } else if (process.stdin.isTTY) {
-            console.error('\n---------------------------------------------------------');
-            console.error('  [Notice] No local VLM model is currently installed.');
-            console.error('  Default Model : smolvlm-500m-q4 (SmolVLM 500M Instruct)');
-            console.error('  Download Size : ~550 MB');
-            console.error('  Target Path   : ~/.cache/termux-vision/models/smolvlm-500m-q4/');
-            console.error('---------------------------------------------------------');
-            const ans = await promptUser('Do you want to download and install this model now? [y/N]: ');
-            if (ans === 'y' || ans === 'yes') {
-              console.error('[*] Downloading smolvlm-500m-q4 (~550MB)...');
-              await cache.install('smolvlm-500m-q4');
-              console.error('[+] Successfully installed smolvlm-500m-q4.');
-              targetModel = 'smolvlm-500m-q4';
-            } else {
-              throw new NoInstalledModelsError(cache.getAvailableCatalogModels());
-            }
-          } else {
-            throw new NoInstalledModelsError(cache.getAvailableCatalogModels());
-          }
-        } else if (installed.length === 1) {
-          targetModel = installed[0].modelId;
-          console.error(`[INFO] Selected installed model: ${targetModel}`);
-        } else {
-          throw new ModelSelectionRequiredError(installed.map(m => m.modelId));
-        }
-      }
-
-      const engine = await load({
-        modelId: targetModel,
-        mmprojPath: mmproj,
-        device: device,
-        runtimePath: runtime,
-        allowDownload: allowDownload,
-        threads: threads ? parseInt(threads, 10) : 4,
-        contextLimit: ctxSize ? parseInt(ctxSize, 10) : null,
-        ngl: ngl ? parseInt(ngl, 10) : null
-      });
-
-      const res = await engine.describe(imagePath, {
-        prompt: prompt,
-        maxTokens: maxTokens ? parseInt(maxTokens, 10) : 150,
-        temperature: temp ? parseFloat(temp) : 0.2,
-        topP: topP ? parseFloat(topP) : undefined,
-        topK: topK ? parseInt(topK, 10) : undefined,
-        repeatPenalty: repeatPenalty ? parseFloat(repeatPenalty) : undefined,
-        seed: seed ? parseInt(seed, 10) : undefined,
-        systemPrompt: systemPrompt || undefined,
-        quality: quality,
-        maxDim: maxDim
-      });
-
-      if (isJson) {
-        console.log(JSON.stringify(res, null, 2));
-      } else {
-        if (res.warnings && res.warnings.length > 0) {
-          for (const w of res.warnings) {
-            console.error(`[WARNING] ${w}`);
-          }
-        }
-        const tpsStr = res.metrics.tokensPerSecond ? ` | ${res.metrics.tokensPerSecond.toFixed(1)} t/s` : '';
-        console.log(`\n[VLM Result | backend=${res.metrics.backend}${tpsStr}]`);
-        console.log(res.text);
-      }
-      process.exit(0);
-    } catch (err) {
-      if (err instanceof VulkanNotAvailableError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(24);
-      } else if (err instanceof RuntimeNotFoundError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(20);
-      } else if (err instanceof NoInstalledModelsError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(21);
-      } else if (err instanceof ModelSelectionRequiredError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(23);
-      } else if (err instanceof ModelNotFoundError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(10);
-      } else if (err instanceof ModelDownloadError) {
-        console.error(`[ERROR] ${err.message}`);
-        process.exit(11);
-      } else {
-        console.error(`[ERROR] VLM execution failed: ${err.message}`);
-        process.exit(15);
-      }
-    }
-  }
-
-  if (command === 'canny') {
-    const imagePath = args[1];
-    if (!imagePath || imagePath.startsWith('-')) {
-      console.error('[ERROR] Missing input image path for Canny edge detection.');
-      console.error('Usage: termux-vision canny <image_path> [options]');
-      process.exit(2);
-    }
-    const resolvedImg = path.resolve(imagePath.replace(/^~(?=$|\/|\\)/, os.homedir()));
-    if (!fs.existsSync(resolvedImg)) {
-      console.error(`[ERROR] Image file not found: '${resolvedImg}'`);
-      process.exit(2);
-    }
-    const outPath = getArg('-o', '--output') || 'edges.png';
-    const low = parseFloat(getArg('--low') || '40.0');
-    const high = parseFloat(getArg('--high') || '120.0');
-    
-    // Execute Canny via Python bridge or fallback
-    const { spawnSync } = require('child_process');
-    const pyRes = spawnSync('python3', [
-      '-m', 'termux_vision.cli.main', 'canny', resolvedImg, '-o', outPath, '--low', String(low), '--high', String(high)
-    ], { stdio: 'inherit' });
-    
-    if (pyRes.status === 0) {
-      process.exit(0);
-    } else {
-      process.exit(pyRes.status || 1);
-    }
+      const checkCmd = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+      const res = execSync(checkCmd, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+      if (res) return cmd;
+    } catch (_) {}
   }
+  return 'python3';
+}
 
-  if (command === 'benchmark') {
-    console.log('=== termux-vision On-Device Benchmark (Node.js Engine) ===');
-    const width = 256;
-    const height = 256;
-    const dummy = new Uint8Array(width * height);
-    for (let i = 0; i < dummy.length; i++) dummy[i] = Math.floor(Math.random() * 256);
+const pythonBin = findPython();
+const args = ['-m', 'termux_vision', ...process.argv.slice(2)];
 
-    const t0 = Date.now();
-    const edges = canny(dummy, width, height, 40, 120);
-    const lat = Date.now() - t0;
-    console.log(`  - Canny Edge Detection (256x256): ${lat} ms`);
-    console.log('[+] Benchmark Complete.');
-    process.exit(0);
-  }
-
-  console.error(`[ERROR] Unknown command: '${command}'`);
-  printHelp();
-  process.exit(2);
-}
+const child = spawn(pythonBin, args, {
+  stdio: 'inherit',
+  env: process.env
+});
 
-main().catch((err) => {
-  console.error(`[FATAL] ${err.message}`);
+child.on('error', (err) => {
+  console.error(`[${'termux_vision'}] Failed to spawn python process (${pythonBin}):`, err.message);
   process.exit(1);
 });
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code || 0);
+  }
+});

package/lib/vlm.js

@@ -45,15 +45,17 @@ function resolveLlamaCli(explicitPath = null) {
   }
 
   const prefix = process.env.PREFIX || '/data/data/com.termux/files/usr';
+  const xdgCache = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
   const candidates = [
-    path.join(os.homedir(), '.termux-llama', 'current', 'bin', 'llama-cli'),
-    path.join(os.homedir(), '.termux-llamacpp', 'current', 'bin', 'llama-cli'),
-    'llama-cli',
+    path.join(xdgCache, 'termux-llamacpp', 'bin', 'llama-cli'),
+    path.join(os.homedir(), '.local', 'bin', 'llama-cli'),
     path.join(prefix, 'bin', 'llama-cli'),
     path.join(prefix, 'bin', 'termux-llama-cli'),
     path.join(prefix, 'bin', 'llama-mtmd-cli'),
-    path.join(os.homedir(), '.local', 'bin', 'llama-cli'),
-    path.join(os.homedir(), 'bin', 'llama-cli')
+    path.join(os.homedir(), '.termux-llamacpp', 'current', 'bin', 'llama-cli'),
+    path.join(os.homedir(), '.termux-llama', 'current', 'bin', 'llama-cli'),
+    path.join(os.homedir(), 'bin', 'llama-cli'),
+    'llama-cli'
   ];
 
   const pathDirs = (process.env.PATH || '').split(path.delimiter);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termux-vision",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "On-device computer vision & VLM multimodal inference framework utilizing device resources for Android Termux & ARM64",
   "main": "index.js",
   "types": "index.d.ts",
@@ -49,10 +49,8 @@
   "bugs": {
     "url": "https://github.com/uno-km/termux-vision/issues"
   },
-  "dependencies": {
-    "@ameva/runtime": ">=2.0.0"
-  },
+  "dependencies": {},
   "engines": {
     "node": ">=16.0.0"
   }
-}
+}