termux-bitnet

Production 1.58-bit (i2_s) BitNet On-Device Inference SDK & CLI for Android Termux & ARM64.

1. Overview & Architecture

termux-bitnet is a native Python SDK and CLI tool designed for running 1.58-bit quantized Large Language Models (BitNet b1.58) directly on Android Termux, ARM64 mobile processors, and edge devices.

The underlying execution engine is written in native C++17 with optimized ARM64 NEON SIMD and DotProd vector instructions (vdotq_s32), exposed to Python via a high-throughput, zero-overhead C-types FFI layer.

[Python 3.8+ Application / CLI]
       │
       ▼ (BitNetEngine / BitNetConfig)
[termux-bitnet Python SDK (ctypes Zero-Copy FFI)]
       │
       ▼ (Strict C ABI: libtermux_bitnet.so)
[Native C++ BitNet Core] ──► ARM64 NEON + DotProd SIMD Vector Kernels

2. Verified BitNet GGUF Model Registry

termux-bitnet provides one-touch model downloading and caching from verified Hugging Face repositories with HTTP Range resume capability:

3. Quick Start

3.1 Installation

# In Android Termux or ARM64 Linux
pip install termux-bitnet

3.2 CLI Commands

# 1. Hardware Diagnostic (Check NEON & DotProd SIMD Acceleration)
termux-bitnet info

# 2. List Available Verified Models
termux-bitnet models

# 3. Download Model with HTTP Range Resume Support
termux-bitnet download bitnet-2b

# 4. Run On-Device Inference
termux-bitnet run -m ~/.cache/termux-bitnet/models/bitnet-2b-ggml-model-i2_s.gguf   -p "The capital of France is"   -t 8 -c 2048 -n 128 --temp 0.7 --top-p 0.95 --top-k 40 --repeat-penalty 1.15

4. Python SDK Usage

4.1 Real-Time Token Streaming

from termux_bitnet import BitNetEngine, BitNetConfig

# 1. Configure Engine Parameters
config = BitNetConfig(
    model_path="~/.cache/termux-bitnet/models/bitnet-2b-ggml-model-i2_s.gguf",
    n_threads=8,
    temperature=0.7,
    top_p=0.95,
    top_k=40,
    min_p=0.05,
    repeat_penalty=1.15,
)

# 2. Stream Generation with Context Manager
with BitNetEngine(config) as engine:
    print("[Prompt]: Write a Python palindrome check function")
    print("[Response]: ", end="", flush=True)
    for token in engine.generate_stream("Write a Python palindrome check:"):
        print(token, end="", flush=True)
    print()

4.2 Programmatic Model Management

from termux_bitnet import download_model, detect_hardware, print_hardware_summary

# Inspect ARM64 Hardware Capabilities
hw = detect_hardware()
print_hardware_summary(hw)

# Download and Cache Model
model_path = download_model("bitnet-2b")
print(f"Model downloaded to: {model_path}")

5. Full Parameter Matrix (BitNetConfig)

6. Physical Device Benchmark (Samsung Galaxy S25 / Termux ARM64)

The following performance metrics were measured directly on a Samsung Galaxy S25 (Snapdragon 8 Elite / Termux Bionic ARM64):

7. License

Apache License 2.0. Copyright (c) 2026 uno-km (AMEVA Foundation).