AMV-BitNet (v2.0.1 Sovereign Ternary)

마이그레이션 안내: 이 패키지는 termux-bitnet에서 amv-bitnet로 이름이 바뀌었습니다. 기존 termux-bitnet 배포본(PyPI/npm)은 호환을 위해 당분간 유지되나 deprecated 상태이며 더 이상 갱신되지 않습니다. pip install amv-bitnet / npm install amv-bitnet로 전환하십시오.

Android Termux 환경 또는 안드로이드 Linux 커널(루팅 없이 Linux 환경이 구동되는 모든 디바이스) 에서 동작합니다 — Termux 전용이 아닙니다.

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

What's New in v2.2.0 — Zero-Compilation Prebuilt Provisioning & Unified Runtime

• Added instant-on auto-provisioning of prebuilt libtermux_bitnet.so on first load without local compilation.
• Unified 1.58-bit ternary GPU shader dispatch through ameva-runtime HAL.
• Verified compatibility with Microsoft BitNet b1.58 PR #633 ternary weight formats.
• Enforced OpenSSF REUSE v3.0 SPDX license headers across all source files.

🏛️ Executive Engineering Disclosure: v2.0.1 Generational Breakthroughs

amv-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 amv-bitnet ameva-runtime

2. Node.js CLI (npm)

npm install -g amv-bitnet @ameva/runtime

3. One-Touch Native Installer

curl -sSL https://raw.githubusercontent.com/uno-km/amv-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/amv-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
...
    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
amv-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
amv-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
amv-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