termux-diffusion 1.0.0__py3-none-any.whl

termux_diffusion/__init__.py

@@ -0,0 +1,74 @@
+"""termux-diffusion: On-Device AI Image Generation Framework for Android Termux & Samsung Galaxy."""
+
+from .core import GenerationResult, async_generate, generate
+from .exceptions import (
+    InferenceTimeoutError,
+    ModelDownloadError,
+    ModelNotFoundError,
+    OOMRiskError,
+    PlatformNotSupportedError,
+    ProvisioningError,
+    TermuxDiffusionError,
+)
+from .hub import (
+    DEFAULT_PRESETS,
+    clear_cache,
+    download_model,
+    get_cache_dir,
+    is_model_cached,
+    list_cached_models,
+    list_presets,
+    register_model,
+    resolve_model_path,
+    set_cache_dir,
+)
+from .installer import locate_sd_cli, provision_engine, run_doctor
+from .platform import (
+    TermuxWakeLock,
+    check_memory_safety,
+    export_to_android_gallery,
+    get_galaxy_gallery_dir,
+    get_memory_info,
+    get_optimal_thread_count,
+    is_android_termux,
+    is_arm64,
+)
+
+__version__ = "1.0.0"
+__author__ = "uno-km (쌩초보코딩단)"
+__license__ = "MIT"
+
+__all__ = [
+    "__version__",
+    "generate",
+    "async_generate",
+    "GenerationResult",
+    "download_model",
+    "resolve_model_path",
+    "register_model",
+    "set_cache_dir",
+    "get_cache_dir",
+    "is_model_cached",
+    "list_cached_models",
+    "clear_cache",
+    "list_presets",
+    "DEFAULT_PRESETS",
+    "locate_sd_cli",
+    "provision_engine",
+    "run_doctor",
+    "is_android_termux",
+    "is_arm64",
+    "check_memory_safety",
+    "get_memory_info",
+    "get_optimal_thread_count",
+    "get_galaxy_gallery_dir",
+    "export_to_android_gallery",
+    "TermuxWakeLock",
+    "TermuxDiffusionError",
+    "PlatformNotSupportedError",
+    "ModelNotFoundError",
+    "ModelDownloadError",
+    "ProvisioningError",
+    "OOMRiskError",
+    "InferenceTimeoutError",
+]

termux_diffusion/cli.py

@@ -0,0 +1,112 @@
+"""Command-line interface entry points for termux-diffusion."""
+
+import argparse
+import sys
+from typing import List, Optional
+
+from .core import generate
+from .hub import clear_cache, download_model, list_cached_models, list_presets
+from .installer import provision_engine, run_doctor
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Main CLI router for termux-diffusion."""
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="termux-diffusion",
+        description="Production On-Device AI Image Generation for Android Termux & Samsung Galaxy."
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # generate command
+    gen_parser = subparsers.add_parser("generate", help="Generate an AI image from a text prompt")
+    gen_parser.add_argument("prompt", type=str, help="Text description of image")
+    gen_parser.add_argument("-m", "--model", type=str, default="realistic", help="Model preset or .gguf path (default: realistic)")
+    gen_parser.add_argument("-n", "--negative", type=str, default=None, help="Negative prompt")
+    gen_parser.add_argument("-s", "--steps", type=int, default=None, help="Denoising steps")
+    gen_parser.add_argument("-c", "--cfg", type=float, default=None, help="CFG guidance scale")
+    gen_parser.add_argument("-W", "--width", type=int, default=512, help="Image width (default: 512)")
+    gen_parser.add_argument("-H", "--height", type=int, default=512, help="Image height (default: 512)")
+    gen_parser.add_argument("-t", "--threads", type=int, default=None, help="CPU threads")
+    gen_parser.add_argument("-o", "--output", type=str, default=None, help="Output file path")
+
+    # install command
+    subparsers.add_parser("install", help="Provision and compile native Bionic C++ engine")
+
+    # doctor command
+    subparsers.add_parser("doctor", help="Run 7-tier pre-flight diagnostic checks")
+
+    # models command
+    subparsers.add_parser("models", help="List available model presets and locally cached weights")
+
+    # download command
+    dl_parser = subparsers.add_parser("download", help="Pre-download a model preset or HF repo")
+    dl_parser.add_argument("model", type=str, help="Model preset name (e.g. realistic, speed, sdxs, turbo, anime)")
+
+    # clear-cache command
+    subparsers.add_parser("clear-cache", help="Delete cached model files to reclaim storage")
+
+    if not argv:
+        parser.print_help()
+        return 0
+
+    args = parser.parse_args(argv)
+
+    if args.command == "generate":
+        res = generate(
+            prompt=args.prompt,
+            model=args.model,
+            negative_prompt=args.negative,
+            steps=args.steps,
+            cfg_scale=args.cfg,
+            width=args.width,
+            height=args.height,
+            threads=args.threads,
+            output=args.output
+        )
+        return 0 if res.path.exists() else 1
+
+    elif args.command == "install":
+        provision_engine(force=True)
+        return 0
+
+    elif args.command == "doctor":
+        ok = run_doctor()
+        return 0 if ok else 1
+
+    elif args.command == "models":
+        print("\n--- 🌟 Available Presets ---")
+        for k, v in list_presets().items():
+            print(f"  • {k:12} : {v['description']} ({v.get('size_mb', 0)}MB)")
+        print("\n--- 💾 Locally Cached Models ---")
+        cached = list_cached_models()
+        if not cached:
+            print("  (No models cached yet. Run 'termux-diffusion download <model>' or generate)")
+        for m in cached:
+            print(f"  • {m['name']:25} [{m['size_mb']} MB] -> {m['path']}")
+        print()
+        return 0
+
+    elif args.command == "download":
+        download_model(args.model)
+        return 0
+
+    elif args.command == "clear-cache":
+        removed = clear_cache()
+        print(f"🧹 Removed {removed} cached model files.")
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+def run_install_cli():
+    """Entry point for termux-diffusion-install."""
+    provision_engine(force=True)
+
+
+def run_doctor_cli():
+    """Entry point for termux-diffusion-doctor."""
+    run_doctor()

termux_diffusion/core.py

@@ -0,0 +1,240 @@
+"""Core generation runner, argument builder, WakeLock wrapper, and gallery bridge."""
+
+import asyncio
+import logging
+import os
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+from .exceptions import InferenceTimeoutError, OOMRiskError, ProvisioningError, TermuxDiffusionError
+from .hub import DEFAULT_PRESETS, list_presets, resolve_model_path
+from .installer import locate_sd_cli, provision_engine
+from .platform import (
+    TermuxWakeLock,
+    check_memory_safety,
+    export_to_android_gallery,
+    get_galaxy_gallery_dir,
+    get_optimal_thread_count,
+)
+
+logger = logging.getLogger("termux_diffusion.core")
+
+
+@dataclass
+class GenerationResult:
+    """Encapsulates the output and metadata of an AI diffusion generation task."""
+    path: Path
+    gallery_path: Optional[Path]
+    prompt: str
+    negative_prompt: Optional[str]
+    model: str
+    device: str
+    steps: int
+    cfg_scale: float
+    width: int
+    height: int
+    seed: int
+    elapsed_sec: float
+
+    def __str__(self) -> str:
+        return f"<GenerationResult path='{self.path}' device='{self.device}' elapsed={self.elapsed_sec:.1f}s>"
+
+
+def generate(
+    prompt: str,
+    model: str = "realistic",
+    negative_prompt: Optional[str] = (
+        "woman, girl, cartoon, anime, 3d render, plastic, illustration, b&w, lowres, blur, deformed hands, extra fingers, messy face, horror"
+    ),
+    device: str = "cpu",
+    steps: Optional[int] = None,
+    cfg_scale: Optional[float] = None,
+    width: int = 512,
+    height: int = 512,
+    seed: int = -1,
+    threads: Optional[int] = None,
+    output: Optional[Union[str, Path]] = None,
+    export_gallery: bool = True,
+    wake_lock: bool = True,
+    low_ram_guard: bool = True,
+    timeout: int = 1800,
+) -> GenerationResult:
+    """Generate an AI image on Samsung Galaxy / Android Termux using Bionic native C++ diffusion.
+    
+    Args:
+        prompt: Detailed text description of the desired image.
+        model: Preset keyword ('realistic', 'speed', 'sdxs', 'turbo', 'anime'), custom repo ('org/repo/file.gguf'), direct URL, or path to .gguf file.
+        negative_prompt: Negative text guidance describing elements to avoid.
+        device: Computing device ('cpu', 'gpu', 'opencl', 'vulkan'). Default is 'cpu'.
+        steps: Number of denoising steps (default determined by preset, e.g. 10).
+        cfg_scale: Classifier-Free Guidance scale (default determined by preset, e.g. 4.0).
+        width: Output image width in pixels (default: 512).
+        height: Output image height in pixels (default: 512).
+        seed: Sampling RNG seed (-1 for random).
+        threads: Number of CPU threads (defaults to optimal big-core cluster count, e.g. 4).
+        output: Destination output filename or path.
+        export_gallery: Whether to copy image to Samsung Gallery and broadcast media scanner intent.
+        wake_lock: Whether to acquire Android CPU WakeLock during generation.
+        low_ram_guard: Whether to verify available memory before starting inference.
+        timeout: Maximum inference timeout in seconds (default: 1800s / 30m).
+    
+    Returns:
+        GenerationResult: Object containing local path, gallery path, and inference metrics.
+    """
+    if not prompt or not prompt.strip():
+        raise ValueError("Prompt must not be empty.")
+
+    device_mode = device.lower().strip()
+    if device_mode not in ("cpu", "gpu", "opencl", "vulkan", "auto"):
+        raise ValueError(f"Invalid device '{device}'. Options: 'cpu', 'gpu', 'opencl', 'vulkan'.")
+
+    # 1. Pre-flight Memory Safety Guard
+    if low_ram_guard:
+        safe, msg = check_memory_safety(required_mb=1000)
+        if not safe:
+            logger.warning("Low RAM Warning: %s", msg)
+
+    # 2. Resolve Model Path & Preset Hyperparameters (Validates model name first)
+    presets = list_presets()
+    model_path = resolve_model_path(model)
+
+    if steps is None:
+        steps = presets.get(model, {}).get("default_steps", 10)
+    if cfg_scale is None:
+        cfg_scale = presets.get(model, {}).get("default_cfg", 4.0)
+    if threads is None:
+        threads = get_optimal_thread_count()
+
+    # 3. Locate or Auto-provision Native sd-cli Engine
+    sd_cli = locate_sd_cli()
+    if not sd_cli:
+        logger.info("sd-cli binary not found in standard paths. Attempting auto-provisioning...")
+        sd_cli = provision_engine()
+
+    # 4. Determine Output Destination
+    timestamp = int(time.time())
+    if output:
+        out_path = Path(os.path.expanduser(str(output))).resolve()
+    else:
+        out_dir = get_galaxy_gallery_dir()
+        out_path = out_dir / f"ai_gen_{timestamp}.png"
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # 5. Build Subprocess Command List (100% List argv, Zero Shell Injection Vector)
+    cmd = [
+        str(sd_cli),
+        "-m", str(model_path),
+        "-p", prompt,
+        "-W", str(width),
+        "-H", str(height),
+        "-t", str(threads),
+        "--steps", str(steps),
+        "--cfg-scale", str(cfg_scale),
+        "-o", str(out_path)
+    ]
+    if negative_prompt:
+        cmd.extend(["-n", negative_prompt])
+    if seed >= 0:
+        cmd.extend(["-s", str(seed)])
+    if device_mode in ("gpu", "opencl", "vulkan"):
+        cmd.extend(["-ngl", "32"])
+
+    logger.info("Executing diffusion inference: %s", " ".join(cmd[:6]) + " ...")
+    print(f"[termux-diffusion] Processing inference with model='{model}' (steps={steps}, threads={threads}, device={device_mode})...")
+
+    start_time = time.time()
+
+    # 6. Execute with WakeLock protection
+    with TermuxWakeLock(enabled=wake_lock):
+        process = None
+        try:
+            process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+                universal_newlines=True
+            )
+
+            # Stream real-time progress to terminal
+            if process.stdout:
+                for line in process.stdout:
+                    line_str = line.strip()
+                    if line_str:
+                        if "step" in line_str.lower() or "%" in line_str or "sampling" in line_str.lower():
+                            print(f"  > {line_str}")
+                        else:
+                            logger.debug("sd-cli: %s", line_str)
+
+            process.wait(timeout=timeout)
+            if process.returncode != 0:
+                raise TermuxDiffusionError(f"Engine process failed with return code {process.returncode}")
+        except KeyboardInterrupt:
+            if process and process.poll() is None:
+                try:
+                    process.kill()
+                    process.wait(timeout=2.0)
+                except Exception:
+                    pass
+            print("\n[termux-diffusion] Inference interrupted by user. Child processes terminated safely.")
+            raise
+        except subprocess.TimeoutExpired as exc:
+            if process and process.poll() is None:
+                try:
+                    process.kill()
+                    process.wait(timeout=2.0)
+                except Exception:
+                    pass
+            raise InferenceTimeoutError(f"Diffusion generation timed out after {timeout} seconds") from exc
+        except Exception:
+            if process and process.poll() is None:
+                try:
+                    process.kill()
+                    process.wait(timeout=2.0)
+                except Exception:
+                    pass
+            raise
+
+    elapsed = time.time() - start_time
+
+    if not out_path.is_file():
+        raise TermuxDiffusionError(f"Engine finished but output file was not created at: {out_path}")
+
+    # 7. Samsung Gallery Export & Media Scanner Broadcast
+    gallery_path = None
+    if export_gallery:
+        try:
+            gallery_path = export_to_android_gallery(out_path)
+        except Exception as e:
+            logger.warning("Could not export to Android gallery: %s", e)
+
+    print(f"[termux-diffusion] Artifact generated in {elapsed:.2f}s -> {out_path}")
+    if gallery_path:
+        print(f"[termux-diffusion] Synchronized to Android MediaStore: {gallery_path}")
+
+    return GenerationResult(
+        path=out_path,
+        gallery_path=gallery_path,
+        prompt=prompt,
+        negative_prompt=negative_prompt,
+        model=model,
+        device=device_mode,
+        steps=steps,
+        cfg_scale=cfg_scale,
+        width=width,
+        height=height,
+        seed=seed,
+        elapsed_sec=elapsed
+    )
+
+
+async def async_generate(*args, **kwargs) -> GenerationResult:
+    """Asynchronous wrapper for generate() to integrate seamlessly into asyncio event loops."""
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, lambda: generate(*args, **kwargs))

termux_diffusion/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions for the termux-diffusion framework."""
+
+class TermuxDiffusionError(Exception):
+    """Base exception for all termux-diffusion errors."""
+    pass
+
+
+class PlatformNotSupportedError(TermuxDiffusionError):
+    """Raised when running on an unsupported platform or non-ARM64 architecture."""
+    pass
+
+
+class ModelNotFoundError(TermuxDiffusionError):
+    """Raised when the specified model preset or file path cannot be located."""
+    pass
+
+
+class ModelDownloadError(TermuxDiffusionError):
+    """Raised when an error occurs during model downloading or checksum verification."""
+    pass
+
+
+class ProvisioningError(TermuxDiffusionError):
+    """Raised when the native C++ engine (sd-cli) fails to build or provision."""
+    pass
+
+
+class OOMRiskError(TermuxDiffusionError):
+    """Raised when available system memory (RAM + zRAM) is insufficient for safe inference."""
+    pass
+
+
+class InferenceTimeoutError(TermuxDiffusionError):
+    """Raised when diffusion inference exceeds the configured execution timeout."""
+    pass