Termux-BitNet (v2.1.0 Sovereign Ternary)

Production-Grade Universal 1.58-Bit (i2_s) On-Device LLM Inference Engine with ARM64 NEON DotProd SIMD & Native Vulkan GPU Acceleration.

🏛️ Executive Engineering Disclosure: v2.0.1 Generational Breakthroughs

termux-bitnet v2.0.1 extends the sovereign ternary architecture with hallucination-prevention prompt wrapping, hardware-level GPU watchdog defense, and dynamic LM Head memory slicing, delivering fully calibrated conversational generation across diverse 1.58-bit models.

📚 Official Academic & Upstream Credibility

• Foundation Technical Whitepaper: AOSF-TR-2026-BITNET-TERNARY-02: Root Cause Analysis of Ternary Numerical Collapse and Dynamic Activation Engine
• Upstream Contributions to Microsoft:
  • microsoft/BitNet #551: Resolved ARM QK=128 stride memory layout desynchronization and word salad.
  • microsoft/BitNet #624: Completed 1x4_32W parallel NEON sdot hardware acceleration kernel and automated Android Termux tooling.
• Upstream Contributions to GGML:
  • ggml-org/whisper.cpp #4089: Mobile heterogeneous GPU-Encoder / CPU-Decoder split-mode architecture.

📑 Supported Pretrained Models & Optimal Settings

🛠️ Comprehensive CLI & SDK Parameter Reference Manual

The inference runtime provides user-directed controls to eliminate hallucinations and tailor execution to mobile hardware:

⚡ Empirical Real-Device Hardware Fleet Scorecard (Ground Truth)

All benchmarks were empirically measured on genuine Samsung Galaxy hardware under unrooted Android Termux Bionic libc environments with steady thermal equilibrium and verified per-device semantic outputs:

📦 Installation

1. Python SDK (PyPI)

# Inside Android Termux (prerequisites: clang cmake python openblas)
pkg update && pkg install -y clang cmake python openblas

# Install Termux-BitNet and AMEVA-Runtime
pip install --upgrade termux-bitnet ameva-runtime

2. Node.js CLI (npm)

npm install -g termux-bitnet @ameva/runtime

3. One-Touch Native Installer

curl -sSL https://raw.githubusercontent.com/uno-km/termux-bitnet/main/install.sh | bash

🚀 Quickstart Recipes

1. Python Programmatic Inference

from termux_bitnet import BitNetEngine, BitNetConfig

# Configure for real-time Falcon-E-1B or BitNet-2B with template wrapping
config = BitNetConfig(
    model_path="~/.cache/termux-bitnet/models/falcon-e-1b-instruct-i2_s.gguf",
    device="gpu",           # "auto", "cpu", or "gpu"
    n_gpu_layers=24,        # 100% GPU offload
    chat_template="falcon", # Formats with <|im_start|>user\n...
    chunk_layers=4,         # Prevent Mali watchdog timeouts
    vocab_slice=32768,      # Slashing LM Head VRAM
    n_threads=4,
    temperature=0.7,
    top_p=0.95
)

with BitNetEngine(config) as engine:
    print("[Prompt]: What is the capital of France?")
    print("[Response]: ", end="", flush=True)
    for token in engine.generate_stream("What is the capital of France?"):
        print(token, end="", flush=True)
    print()
    metrics = engine.get_last_metrics()
    print(f"Speed: {metrics.tokens_per_second:.2f} tok/s")

2. Standalone CLI Usage

# 1. Run 1B real-time conversational model with Falcon wrapping
termux-bitnet run -m models/falcon-e-1b-instruct-i2_s.gguf \
  -p "What is the capital of France?" --prompt-template falcon -ngl 24 -t 4

# 2. Run Microsoft BitNet 2B with Squared ReLU
termux-bitnet run -m models/bitnet-2b-ggml-model-i2_s.gguf \
  -p "What is the capital of France?" --act-fn relu2 --prompt-template raw -ngl 30 -t 4

# 3. Run 7.45B model on 6GB RAM device with GPU Chunking and Vocab Slicing
termux-bitnet run -m models/falcon3-7b-instruct-1.58bit-i2_s.gguf \
  -p "Explain quantum computing simply" --prompt-template chatml \
  --chunk-layers 4 --vocab-slice 32768 -ngl 12 -t 4

Distributed Clustering & Memory Pooling (AMEVA-Cluster)

Termux-BitNet integrates with AMEVA-Cluster (pip install ameva-cluster) for distributed 1.58-bit ternary tensor sharding and cross-device memory pooling.

1. Install Cluster Runtime

pip install ameva-cluster
# or Node.js:
npm install @ameva/cluster

2. Launch Worker Node on Remote Phone

# On remote worker device (e.g. Galaxy A53):
ameva-cluster worker --port 50052

3. Run Distributed 1.58-Bit Inference

# Master node sharding Falcon3-7B or BitNet-2B across remote phones:
termux-bitnet run -m models/bitnet_b1_58-3B.gguf \
  --rpc 192.0.2.10:50052,192.0.2.11:50052 \
  -p "Explain ternary quantization benefits."

from termux_bitnet import BitNetEngine, BitNetConfig

config = BitNetConfig(
    model_path="models/bitnet_b1_58-3B.gguf",
    cluster_rpc_servers="192.0.2.10:50052,192.0.2.11:50052"
)
with BitNetEngine(config) as engine:
    for token in engine.generate_stream("Distributed clustering active across ternary nodes."):
        print(token, end="", flush=True)

🌐 Ecosystem Links & Documentation

• Official Documentation Portal: https://uno-km.vercel.app/lib/bitnet/
• Foundation Research Lab: https://uno-km.vercel.app/labs/
• License: Apache-2.0
• Governance: AMEVA Open-Source Foundation (AOSF) & @uno-km