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. 아키텍처 철학: "Single C++ Core, Dual Thin Gateways"

termux-bitnet은 **"연산과 텐서 제어의 모든 핵심(Heavy Lifting)은 오직 순수 C++ 단 한 곳에서만 수행하고, Python(pip)과 Node.js(npm)는 제로 오버헤드로 C++ 엔진에 진입하는 경량 입구(Thin Gateway / FFI Boundary) 역할만 수행한다"**는 글로벌 표준 오픈소스 AI 엔진 설계 원칙을 철저히 준수합니다.

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 Model Registry)

termux-bitnet은 Hugging Face 상의 공식/커뮤니티 1.58-bit GGUF 모델을 지원하며, 내장 다운로더(download)를 통해 원터치로 캐싱 및 구동할 수 있습니다:

# 모델 원터치 다운로드 (이어받기 지원)
termux-bitnet download bitnet-2b

3. 빠른 시작 (Quick Start)

3.1 Python Gateway (pip)

# 설치
pip install termux-bitnet

# 실행 (풀 파라미터 제어)
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)

# 설치
npm install termux-bitnet

# 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. C ABI 직접 임베딩 (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.