Termux-BitNet (v2.0.1 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 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

🌐 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