termux-diffusion 1.0.0__py3-none-any.whl

termux_diffusion/platform.py

@@ -0,0 +1,220 @@
+"""Platform inspection, Samsung Galaxy hardware detection, memory checks, and Android OS bridges."""
+
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+logger = logging.getLogger("termux_diffusion.platform")
+
+# Android Termux standard paths
+TERMUX_PREFIX = os.environ.get("PREFIX", "/data/data/com.termux/files/usr")
+TERMUX_HOME = os.environ.get("HOME", "/data/data/com.termux/files/home")
+
+
+def is_android_termux() -> bool:
+    """Check whether the current runtime environment is native Android Termux."""
+    if os.environ.get("TERMUX_VERSION") or os.environ.get("TERMUX_APP_PID"):
+        return True
+    if os.path.exists("/data/data/com.termux"):
+        return True
+    if os.path.exists(f"{TERMUX_PREFIX}/bin/pkg"):
+        return True
+    return False
+
+
+def is_arm64() -> bool:
+    """Check whether the host CPU architecture is 64-bit ARM (aarch64 / arm64)."""
+    machine = platform.machine().lower()
+    return machine in ("aarch64", "arm64", "armv8l", "armv8b")
+
+
+def get_default_cache_dir() -> Path:
+    """Return default cache directory for models and downloaded assets."""
+    custom_cache = os.environ.get("TERMUX_DIFFUSION_CACHE")
+    if custom_cache:
+        path = Path(os.path.expanduser(custom_cache)).resolve()
+    else:
+        path = Path(os.path.expanduser("~/.cache/termux-diffusion")).resolve()
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_galaxy_gallery_dir() -> Path:
+    """Resolve and ensure the Samsung Galaxy / Android media pictures directory."""
+    # Preferred: ~/storage/pictures/TermuxDiffusion
+    user_pictures = Path(os.path.expanduser("~/storage/pictures/TermuxDiffusion"))
+    if user_pictures.parent.exists():
+        user_pictures.mkdir(parents=True, exist_ok=True)
+        return user_pictures
+
+    # Secondary: /storage/emulated/0/Pictures/TermuxDiffusion
+    sdcard_pictures = Path("/storage/emulated/0/Pictures/TermuxDiffusion")
+    try:
+        sdcard_pictures.mkdir(parents=True, exist_ok=True)
+        return sdcard_pictures
+    except (PermissionError, OSError):
+        pass
+
+    # Fallback to local workspace output directory
+    fallback = get_default_cache_dir() / "outputs"
+    fallback.mkdir(parents=True, exist_ok=True)
+    return fallback
+
+
+def export_to_android_gallery(source_image_path: Path, destination_name: Optional[str] = None) -> Path:
+    """Copy rendered image to Samsung Gallery directory and broadcast media scanner intent.
+    
+    This ensures that images generated by termux-diffusion appear immediately in
+    the Samsung Gallery app without requiring a reboot.
+    """
+    source_image_path = Path(source_image_path).resolve()
+    if not source_image_path.exists():
+        raise FileNotFoundError(f"Source image does not exist: {source_image_path}")
+
+    dest_dir = get_galaxy_gallery_dir()
+    if destination_name is None:
+        destination_name = source_image_path.name
+
+    dest_path = dest_dir / destination_name
+    shutil.copy2(source_image_path, dest_path)
+    logger.info("Exported AI image to Samsung Gallery path: %s", dest_path)
+
+    # Broadcast media scanner intent if on Android
+    _trigger_media_scanner(dest_path)
+    return dest_path
+
+
+def _trigger_media_scanner(image_path: Path) -> None:
+    """Broadcast android.intent.action.MEDIA_SCANNER_SCAN_FILE so Galaxy Gallery indexes the file."""
+    if not is_android_termux():
+        return
+
+    am_binary = shutil.which("am") or shutil.which("termux-am")
+    if not am_binary:
+        return
+
+    file_uri = f"file://{image_path.resolve()}"
+    try:
+        subprocess.run(
+            [am_binary, "broadcast", "-a", "android.intent.action.MEDIA_SCANNER_SCAN_FILE", "-d", file_uri],
+            capture_output=True,
+            timeout=3.0,
+            check=False
+        )
+    except Exception as exc:
+        logger.debug("Media scanner broadcast note: %s", exc)
+
+
+def get_optimal_thread_count() -> int:
+    """Calculate the optimal number of inference threads for Galaxy Exynos / Snapdragon CPUs.
+    
+    In big.LITTLE architectures (e.g. 4 Performance + 4 Efficiency cores), running on all 8
+    cores causes severe thermal throttling and cache thrashing. Using the performance cluster
+    count (typically 4 threads) yields faster inference and lower heat.
+    """
+    total_cores = os.cpu_count() or 4
+    if total_cores >= 8:
+        return 4
+    elif total_cores >= 6:
+        return 4
+    elif total_cores >= 4:
+        return 4
+    return max(1, total_cores)
+
+
+def get_memory_info() -> Dict[str, int]:
+    """Inspect /proc/meminfo to retrieve RAM and Samsung RAM Plus (zRAM swap) metrics in MB."""
+    metrics = {
+        "mem_total_mb": 0,
+        "mem_available_mb": 0,
+        "swap_total_mb": 0,
+        "swap_free_mb": 0,
+        "effective_total_mb": 0,
+        "effective_available_mb": 0,
+    }
+    
+    if not os.path.exists("/proc/meminfo"):
+        # Fallback for mock/test environments
+        metrics["mem_total_mb"] = 6144
+        metrics["mem_available_mb"] = 3072
+        metrics["swap_total_mb"] = 4096
+        metrics["swap_free_mb"] = 4096
+        metrics["effective_total_mb"] = 10240
+        metrics["effective_available_mb"] = 7168
+        return metrics
+
+    try:
+        with open("/proc/meminfo", "r", encoding="utf-8") as f:
+            for line in f:
+                parts = line.split(":")
+                if len(parts) == 2:
+                    key = parts[0].strip()
+                    val_str = parts[1].strip().split()[0]
+                    if val_str.isdigit():
+                        val_kb = int(val_str)
+                        val_mb = val_kb // 1024
+                        if key == "MemTotal":
+                            metrics["mem_total_mb"] = val_mb
+                        elif key == "MemAvailable":
+                            metrics["mem_available_mb"] = val_mb
+                        elif key == "SwapTotal":
+                            metrics["swap_total_mb"] = val_mb
+                        elif key == "SwapFree":
+                            metrics["swap_free_mb"] = val_mb
+    except Exception as e:
+        logger.debug("Failed reading /proc/meminfo: %s", e)
+
+    metrics["effective_total_mb"] = metrics["mem_total_mb"] + metrics["swap_total_mb"]
+    metrics["effective_available_mb"] = metrics["mem_available_mb"] + metrics["swap_free_mb"]
+    return metrics
+
+
+def check_memory_safety(required_mb: int = 1500) -> Tuple[bool, str]:
+    """Verify if available memory is sufficient for model loading without triggering Android LMK."""
+    mem = get_memory_info()
+    avail = mem["effective_available_mb"]
+    if avail < required_mb:
+        return False, (
+            f"Available memory ({avail} MB) is below the recommended threshold ({required_mb} MB). "
+            f"Please enable Samsung RAM Plus (Settings -> Battery and device care -> Memory -> RAM Plus) "
+            f"or close background apps to avoid Low Memory Killer (LMK) termination."
+        )
+    return True, f"Memory check passed: {avail} MB available (RAM + zRAM)."
+
+
+class TermuxWakeLock:
+    """Context manager to hold Android CPU WakeLock during long-running AI inference."""
+    
+    def __init__(self, enabled: bool = True):
+        self.enabled = enabled
+        self._acquired = False
+
+    def __enter__(self):
+        if not self.enabled or not is_android_termux():
+            return self
+
+        wake_lock_bin = shutil.which("termux-wake-lock")
+        if wake_lock_bin:
+            try:
+                subprocess.run([wake_lock_bin], capture_output=True, timeout=2.0, check=False)
+                self._acquired = True
+                logger.debug("Acquired Termux CPU WakeLock.")
+            except Exception as e:
+                logger.debug("Failed acquiring WakeLock: %s", e)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self._acquired:
+            wake_unlock_bin = shutil.which("termux-wake-unlock")
+            if wake_unlock_bin:
+                try:
+                    subprocess.run([wake_unlock_bin], capture_output=True, timeout=2.0, check=False)
+                    logger.debug("Released Termux CPU WakeLock.")
+                except Exception as e:
+                    logger.debug("Failed releasing WakeLock: %s", e)
+            self._acquired = False

termux_diffusion/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561.

termux_diffusion-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 uno-km (쌩초보코딩단)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

termux_diffusion-1.0.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.1
+Name: termux-diffusion
+Version: 1.0.0
+Summary: Production On-Device AI Image Generation Framework for Android Termux & Samsung Galaxy (Dual-Engine Python & Node.js)
+Home-page: https://github.com/uno-km/termux-diffusion
+Author: uno-km (쌩초보코딩단)
+Author-email: "uno-km (쌩초보코딩단)" <hosequelbo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/uno-km/termux-diffusion
+Project-URL: Documentation, https://uno-km.github.io/termux-diffusion/
+Project-URL: npm Package, https://www.npmjs.com/package/termux-diffusion
+Project-URL: Bug Tracker, https://github.com/uno-km/termux-diffusion/issues
+Project-URL: Source, https://github.com/uno-km/termux-diffusion
+Keywords: stable-diffusion,diffusion,termux,android,samsung-galaxy,edge-ai,on-device-ai,image-generation,gguf,arm64,bionic-libc,snapdragon,exynos,text-to-image,txt2img,mobile-ai,quantization,generative-ai,vulkan,opencl,offline-ai,private-ai,ai-art,comfyui-alternative,webui-alternative
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# Termux-Diffusion
+
+**Production On-Device AI Image Generation Framework for Android Termux & Samsung Galaxy**  
+*Dual-Engine Architecture (Python & Node.js / TypeScript) with Native Bionic ARM64 Tensor Acceleration*
+
+[![PyPI Version](https://img.shields.io/pypi/v/termux-diffusion.svg?color=blue)](https://pypi.org/project/termux-diffusion/)
+[![npm Version](https://img.shields.io/npm/v/termux-diffusion.svg?color=red)](https://www.npmjs.com/package/termux-diffusion)
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://pypi.org/project/termux-diffusion/)
+[![Node Version](https://img.shields.io/badge/node-16+-brightgreen.svg)](https://www.npmjs.com/package/termux-diffusion)
+[![Platform](https://img.shields.io/badge/platform-Android%20Termux%20(ARM64)-green.svg)](https://github.com/uno-km/termux-diffusion)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## 1. System Overview
+
+`termux-diffusion` is an enterprise-grade, on-device AI text-to-image synthesis pipeline designed specifically for Android Termux environments and Samsung Galaxy hardware.
+
+Unlike desktop-centric WebUI ports that require heavy containerization (e.g., PRoot Linux / Ubuntu) or suffer from memory exhaustion under the Android Low Memory Killer (LMK), `termux-diffusion` executes directly against native Android Bionic `libc` with ARM64 NEON SIMD vectorization and GGML quantized tensor weights.
+
+---
+
+## 2. Automated Bootstrap & Installation
+
+### Option A: One-Line Zero-Touch Bootstrap (Recommended)
+
+Run the platform bootstrap script in Termux to automatically verify toolchains, storage permissions, and native engine binaries:
+
+#### Python Runtime
+```bash
+curl -sL https://raw.githubusercontent.com/uno-km/termux-diffusion/main/docs/install.sh | bash
+```
+
+#### Node.js / TypeScript Runtime
+```bash
+curl -sL https://raw.githubusercontent.com/uno-km/termux-diffusion/main/docs/install-node.sh | bash
+```
+
+---
+
+### Option B: Package Manager Installation
+
+#### Python (PyPI)
+```bash
+pip install termux-diffusion && termux-diffusion-install
+```
+
+#### Node.js (npm)
+```bash
+npm install -g termux-diffusion && npx termux-diffusion install
+```
+
+---
+
+## 3. Core Architectural Capabilities
+
+* **Zero-PRoot Native Bionic Execution:** Executes natively on ARM64 without container overhead, achieving maximum memory efficiency.
+* **Integrated Model Hub:** Built-in streaming downloader with automatic checksum verification and cache persistence.
+* **Power & WakeLock Management (`TermuxWakeLock`):** Automatically holds Android CPU WakeLock during inference, preventing kernel suspension when the screen turns off.
+* **Low-Memory & LMK Guard:** Inspects physical memory and Android zRAM (Samsung RAM Plus) before allocating tensor weight buffers.
+* **Samsung Gallery Integration:** Automatically persists generated outputs to `~/storage/pictures/TermuxDiffusion/` and triggers `android.intent.action.MEDIA_SCANNER_SCAN_FILE` for instant indexing in Samsung Gallery.
+* **big.LITTLE Core Affinity Tuning:** Auto-detects Exynos (e.g., 1380, 1480, 2400) and Snapdragon cluster topologies to maintain high sustained clock rates without thermal throttling.
+* **Hardware Compute Selection:** Explicit compute backend targeting via `device="cpu"` or `device="gpu"`.
+
+---
+
+## 4. Built-in Model Hub Presets
+
+| Preset | Model & Quantization | Size | Latency Baseline (Exynos 1380) | Recommended Workload |
+| :--- | :--- | :---: | :---: | :--- |
+| **`"realistic"`** | Realistic Vision V6.0 B1 (Q4_K) | 1.62 GB | ~25 min (10 steps) | High-fidelity photorealism (portraits, skin textures, lighting) |
+| **`"speed"`** | Stable Diffusion 1.5 Base (Q4_1) | 1.59 GB | ~15 min (10 steps) | General-purpose drafting and composition |
+| **`"sdxs"`** | SDXS 512-0.9 Mobile (Q4_0) | **450 MB** | **~2.5 min (2 steps)** | Ultra-low latency mobile prototyping |
+| **`"turbo"`** | SD Turbo (Q4_0) | 1.20 GB | ~4 min (1 step) | Single-step real-time inference |
+| **`"anime"`** | DreamShaper 8 (Q4_K) | 1.65 GB | ~20 min (10 steps) | 2D / 2.5D stylized illustration and animation art |
+
+---
+
+## 5. Usage & Integration
+
+### Python API
+
+```python
+from termux_diffusion import generate
+
+result = generate(
+    prompt="RAW photo, portrait of a happy smiling young Korean man in his 30s wearing glasses and hoodie, working on laptop, photorealistic, cinematic",
+    model="realistic",
+    device="cpu",
+    steps=10,
+    cfg_scale=4.0,
+    output="developer.png"
+)
+
+print(f"Output Path: {result.path}")
+print(f"Android MediaStore: {result.gallery_path}")
+print(f"Elapsed Time: {result.elapsed_sec:.2f}s")
+```
+
+### Node.js / TypeScript API
+
+```javascript
+const { generate } = require('termux-diffusion');
+
+async function main() {
+    const result = await generate({
+        prompt: 'cyberpunk cat with neon collar in rainy alley, 8k, photorealistic',
+        model: 'speed',
+        device: 'cpu',
+        steps: 10,
+        output: 'cyber_cat.png'
+    });
+
+    console.log(`Output Path: ${result.path}`);
+    console.log(`Android MediaStore: ${result.galleryPath}`);
+}
+
+main().catch(console.error);
+```
+
+---
+
+## 6. Custom Models & Hugging Face Resolution
+
+### 1. Direct Hugging Face Repository Identifier
+Pass any repository ID and `.gguf` filename. The framework resolves, streams, caches, and executes the weights:
+```python
+generate(
+    "1girl, anime masterpiece, vibrant colors",
+    model="second-state/DreamShaper-8-GGUF/dreamshaper-8-Q4_k.gguf"
+)
+```
+
+### 2. Local File Reference
+```python
+generate(
+    "fantasy landscape at sunrise",
+    model="~/storage/downloads/custom_model.gguf"
+)
+```
+
+### 3. Alias Registration (`register_model`)
+```python
+from termux_diffusion import register_model, generate
+
+register_model("waifu", repo_id="second-state/DreamShaper-8-GGUF", filename="dreamshaper-8-Q4_k.gguf")
+generate("anime portrait", model="waifu")
+```
+
+---
+
+## 7. Pre-flight Diagnostic Tool
+
+Verify system packages, architecture, available memory, and native engine status:
+
+```bash
+# Python
+termux-diffusion-doctor
+
+# Node.js
+npx termux-diffusion doctor
+```
+
+---
+
+## 8. License
+
+Released under the **MIT License**. Maintained by **uno-km**.

termux_diffusion-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+termux_diffusion/__init__.py,sha256=W7ZaFDqFF5MRCzlhtOKjT4yj_PXgDRswsIbrMhHQtLI,1736
+termux_diffusion/cli.py,sha256=KPIlBN1ahruftqRNwG3-e7TAYnC6WjbPK5TZAwvvBsU,4149
+termux_diffusion/core.py,sha256=rZPiXrlD9p9EQKBEL78iu6Nvpcdjl_8cEpPboi8g8nE,8855
+termux_diffusion/exceptions.py,sha256=3p-dDVdbJImyhUyKwcv_wsuuGldBUBe_9ccA_9g2rgk,1032
+termux_diffusion/hub.py,sha256=K6DO1rGGQ1o-kmh05XIEhPyCWVBwDtRBqSW79p_mG3g,13038
+termux_diffusion/installer.py,sha256=zHEyfVxldCTV8dA-Gui9t6YIugpVulrBP_bnKC3h1ZQ,7631
+termux_diffusion/platform.py,sha256=izwn2akbhvdvq_DuYddv0fLZrIzEJcv2gmvXjR73tNc,8338
+termux_diffusion/py.typed,sha256=bWew9mHgMy8LqMu7RuqQXFXLBxh2CRx0dUbSx-3wE48,27
+termux_diffusion-1.0.0.dist-info/LICENSE,sha256=Ek5JuH4HK-oMetVBul6Ovr7D6MVfNkPrSOpWqIwiCXI,1084
+termux_diffusion-1.0.0.dist-info/METADATA,sha256=FxhuVYr9BpYwsTNjoG4-7K2t7MX0H1W7sILOoaQWdcw,8080
+termux_diffusion-1.0.0.dist-info/WHEEL,sha256=y4mX-SOX4fYIkonsAGA5N0Oy-8_gI4FXw5HNI1xqvWg,91
+termux_diffusion-1.0.0.dist-info/entry_points.txt,sha256=8vBahKNnbeneyBq3Jgu-ZfeeX5NsK09iG9pJ_CUaIt0,189
+termux_diffusion-1.0.0.dist-info/top_level.txt,sha256=3rMTnjMa0GVaZgixdY5fn-Drj3LkxJ-jQW3KjzkWodA,17
+termux_diffusion-1.0.0.dist-info/RECORD,,

termux_diffusion-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (70.2.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

termux_diffusion-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+termux-diffusion = termux_diffusion.cli:main
+termux-diffusion-doctor = termux_diffusion.cli:run_doctor_cli
+termux-diffusion-install = termux_diffusion.cli:run_install_cli

termux_diffusion-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+termux_diffusion