termux-bitnet

Single C++ Core & Multi-Language Thin Gateways (Python SDK + Node.js npm) for 1.58-bit (i2_s) BitNet On-Device Inference on Android Termux & ARM64.

1. Architectural Philosophy: "Single C++ Core, Dual Thin Gateways"

termux-bitnet strictly adheres to the standard open-source AI systems design principle: "All heavy computation, memory management, and tensor algebra are executed exclusively in a single high-performance C++ core, while Python (pip) and Node.js (npm) act as zero-overhead lightweight entry points (Thin Gateways / FFI Boundaries)."

graph TD
    subgraph Gateways ["Multi-Language Thin Gateways (Lightweight Entry Points)"]
        G1["Python Gateway<br/><code>pip install termux-bitnet</code><br/>(ctypes Zero-Copy FFI)"]
        G2["Node.js / TS Gateway<br/><code>npm install termux-bitnet</code><br/>(Native CLI / IPC)"]
        G3["Native CLI<br/><code>termux-bitnet-cli</code>"]
    end

    subgraph Boundary ["Strict C ABI Boundary (include/termux_bitnet.h)"]
        ABI["bitnet_init() | bitnet_eval() | bitnet_generate_stream() | bitnet_free()"]
    end

    subgraph Core ["Single High-Performance C++ Core (libtermux_bitnet.so)"]
        K1["ARM64 NEON + DotProd Accel (vdotq_s32)"]
        K2["ARM64 NEON + FMA Fallback (vmlal_s8)"]
        K3["QK=128 32-Stride Interleaved Scalar Fallback"]
        KV["KV Cache & Top-P / Temperature Sampler"]
    end

    G1 --> ABI
    G2 --> ABI
    G3 --> ABI
    ABI --> Core

2. Verified BitNet Model Registry

termux-bitnet supports verified official and community 1.58-bit GGUF models on Hugging Face. Download and cache models with single-command HTTP Range resume support:

# One-touch download with HTTP resume support
termux-bitnet download bitnet-2b

3. Quick Start

3.1 Python Gateway (pip)

# Install Python package
pip install termux-bitnet

# Run inference CLI with full parameter matrix control
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

from termux_bitnet import BitNetEngine, BitNetConfig

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,
)

with BitNetEngine(config) as engine:
    for token in engine.generate_stream("Write a Python palindrome check:"):
        print(token, end="", flush=True)

3.2 Node.js Gateway (npm)

# Install npm package
npm install termux-bitnet

# Run Node.js CLI
npx termux-bitnet run -p "Explain harmonic mean in one sentence" -t 8 --temp 0.7 --top-p 0.95

const { createEngine } = require('termux-bitnet');

async function main() {
  const engine = createEngine({
    threads: 8,
    temperature: 0.7,
    topP: 0.95,
    topK: 40,
    repeatPenalty: 1.15,
  });
  
  await engine.generateStream('Question: Explain harmonic mean:', 128, (token) => {
    process.stdout.write(token);
  });
}

main();

4. Full Parameter Matrix

5. Direct C ABI Embedding (C/C++)

#include "termux_bitnet.h"
#include <stdio.h>

int main() {
    bitnet_params_t params = bitnet_default_params();
    params.temperature = 0.7f;
    params.top_p = 0.95f;
    params.top_k = 40;
    bitnet_context_t ctx = bitnet_init(&params);

    bitnet_generate_stream(ctx, "The capital of France is", 64, 
        [](const char* token, int32_t id, void* u) {
            printf("%s", token);
            return true;
        }, NULL);

    bitnet_free(ctx);
    return 0;
}

6. License

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