termux-bitnet 1.0.0__tar.gz

termux_bitnet-1.0.0/CMakeLists.txt

@@ -0,0 +1,71 @@
+cmake_minimum_required(VERSION 3.14)
+project(termux_bitnet LANGUAGES C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Optimization Options
+option(BUILD_SHARED_LIBS "Build shared libraries" ON)
+option(GGML_NEON "Enable ARM NEON SIMD optimizations" ON)
+option(GGML_ARM_DOTPROD "Enable ARM Dot Product extension" AUTO)
+option(BUILD_CLI "Build native standalone CLI" ON)
+
+# Compiler Optimization Flags
+if(MSVC)
+    add_compile_options(/O2 /W3 /utf-8)
+else()
+    add_compile_options(-O3 -Wall -Wextra -Wno-unused-parameter)
+    if(CMAKE_SYSTEM_PROCESSOR MATCHES "aarch64|arm64")
+        if(GGML_NEON)
+            add_definitions(-D__ARM_NEON)
+            if(GGML_ARM_DOTPROD)
+                add_compile_options(-march=armv8.2-a+dotprod+fp16)
+                add_definitions(-D__ARM_FEATURE_DOTPROD=1)
+            else()
+                add_compile_options(-march=armv8-a+simd+fp16)
+            endif()
+        endif()
+    elseif(CMAKE_SYSTEM_PROCESSOR MATCHES "x86_64|AMD64")
+        # x86 Fallback / Development environment
+        if(NOT MSVC)
+            add_compile_options(-mavx2 -mfma)
+        endif()
+    endif()
+endif()
+
+# Include Directories
+include_directories(
+    ${CMAKE_CURRENT_SOURCE_DIR}/include
+    ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+
+# Core Sources
+set(BITNET_CORE_SOURCES
+    src/ggml_bitnet_mad.cpp
+    src/llama_bitnet_core.cpp
+    src/c_api.cpp
+)
+
+# Shared Library for Python SDK & C/C++ Embedding
+add_library(termux_bitnet SHARED ${BITNET_CORE_SOURCES})
+target_include_directories(termux_bitnet PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
+
+if(UNIX AND NOT APPLE)
+    target_link_libraries(termux_bitnet PRIVATE m pthread dl)
+endif()
+
+# Native CLI Application
+if(BUILD_CLI)
+    add_executable(termux-bitnet-cli src/main.cpp)
+    target_link_libraries(termux-bitnet-cli PRIVATE termux_bitnet)
+    target_include_directories(termux-bitnet-cli PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/include)
+endif()
+
+# Install Directives
+install(TARGETS termux_bitnet
+    LIBRARY DESTINATION lib
+    ARCHIVE DESTINATION lib
+    RUNTIME DESTINATION bin
+)
+install(FILES include/termux_bitnet.h DESTINATION include)

termux_bitnet-1.0.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright (c) 2026 uno-km (https://github.com/uno-km)
+
+   Licensed under the Apache License, Version 2.0 (the " License\);
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an \AS IS\ BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.

termux_bitnet-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include CMakeLists.txt
+recursive-include include *.h
+recursive-include src *.cpp *.h
+recursive-include termux_bitnet *.py

termux_bitnet-1.0.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.1
+Name: termux-bitnet
+Version: 1.0.0
+Summary: High-performance 1.58-bit BitNet inference engine, Python SDK & CLI optimized for Android Termux and ARM64 architecture.
+Author-email: uno-km <unokim.dev@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/uno-km/termux-bitnet
+Project-URL: Documentation, https://uno-km.github.io/termux-bitnet/
+Project-URL: Repository, https://github.com/uno-km/termux-bitnet.git
+Project-URL: Issues, https://github.com/uno-km/termux-bitnet/issues
+Keywords: bitnet,1-bit-llm,termux,arm64,neon,dotprod,edge-ai,on-device-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: C++
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Android
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tqdm>=4.64.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: server
+Requires-Dist: uvicorn>=0.20.0; extra == "server"
+Requires-Dist: fastapi>=0.95.0; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
+
+# 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.**
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Architecture](https://img.shields.io/badge/Core-Native%20C++17%20|%20NEON%20|%20DotProd-brightgreen.svg)]()
+[![Python SDK](https://img.shields.io/badge/Gateway-pip%20install%20termux--bitnet-blue.svg)]()
+[![Node.js SDK](https://img.shields.io/badge/Gateway-npm%20install%20termux--bitnet-red.svg)]()
+[![Platform](https://img.shields.io/badge/Platform-Android%20Termux%20|%20PRoot%20|%20Linux-orange.svg)]()
+
+---
+
+## 1. 아키텍처 철학: "Single C++ Core, Dual Thin Gateways"
+
+`termux-bitnet`은 **"연산과 텐서 제어의 모든 핵심(Heavy Lifting)은 오직 순수 C++ 단 한 곳에서만 수행하고, Python(`pip`)과 Node.js(`npm`)는 제로 오버헤드로 C++ 엔진에 진입하는 경량 입구(Thin Gateway / FFI Boundary) 역할만 수행한다"**는 글로벌 표준 오픈소스 AI 엔진 설계 원칙을 철저히 준수합니다.
+
+```mermaid
+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`)를 통해 원터치로 캐싱 및 구동할 수 있습니다:
+
+| Alias | 원본 저장소 및 모델 파일 | 파라미터 / 용량 | 특징 |
+|---|---|---|---|
+| `bitnet-2b` | `microsoft/bitnet-b1.58-2B-4T-gguf` | 2.4B / **1.13 GB** | Microsoft 공식 1.58-bit 플래그십 (모바일 권장) |
+| `bitnet-large` | `RichardErkhov/1bitLLM_-_bitnet_b1_58-large-gguf` | 0.7B / **404 MB** | 저사양 모바일/Termux 기기용 초경량 엔진 |
+| `bitnet-3b` | `Green-Sky/bitnet_b1_58-3B-GGUF` | 3.3B / **730 MB** | 대용량 고정밀 온디바이스 모델 |
+| `bitnet-3b-q4` | `RichardErkhov/1bitLLM_-_bitnet_b1_58-3B-gguf` | 3.3B / **1.83 GB** | Q4 양자화 고성능 3B 모델 |
+
+```bash
+# 모델 원터치 다운로드 (이어받기 지원)
+termux-bitnet download bitnet-2b
+```
+
+---
+
+## 3. 빠른 시작 (Quick Start)
+
+### 3.1 Python Gateway (`pip`)
+
+```bash
+# 설치
+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
+```
+
+```python
+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`)
+
+```bash
+# 설치
+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
+```
+
+```javascript
+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)
+
+| CLI Flag | Python (`BitNetConfig`) | Node.js (`BitNetOptions`) | C ABI (`bitnet_params_t`) | 기본값 | 설명 |
+|---|---|---|---|---|---|
+| `-m, --model` | `model_path` | `modelPath` | `model_path` | `""` | GGUF 모델 파일 경로 |
+| `-p, --prompt` | `prompt` | `prompt` | `prompt` | `""` | 입력 프롬프트 텍스트 |
+| `-t, --threads` | `n_threads` | `threads` | `n_threads` | `cores` | CPU 워커 스레드 수 |
+| `-c, --ctx-size` | `n_ctx` | `contextSize` | `n_ctx` | `2048` | KV Cache 컨텍스트 윈도우 크기 |
+| `-b, --batch-size`| `n_batch` | `batchSize` | `n_batch` | `512` | 프롬프트 평가 배치 크기 |
+| `-n, --n-predict` | `n_predict` | `maxTokens` | `n_predict` | `128` | 최대 생성 토큰 수 |
+| `--temp` | `temperature` | `temperature` | `temperature` | `0.7` | Softmax 온도 (0.0=Greedy) |
+| `--top-p` | `top_p` | `topP` | `top_p` | `0.95` | Nucleus Top-P 샘플링 |
+| `--top-k` | `top_k` | `topK` | `top_k` | `40` | Top-K 샘플링 컷오프 |
+| `--min-p` | `min_p` | `minP` | `min_p` | `0.05` | Min-P 상대 확률 컷오프 |
+| `--repeat-penalty`| `repeat_penalty` | `repeatPenalty` | `repeat_penalty` | `1.15` | 반복 토큰 억제 계수 |
+| `-s, --seed` | `seed` | `seed` | `seed` | `0` | 난수 시드 (0=무작위) |
+| `--system-prompt` | `system_prompt` | `systemPrompt` | `system_prompt` | `""` | 시스템 프롬프트 접두사 |
+| `-r, --stop` | `stop_tokens` | `stopTokens` | `stop_tokens` | `""` | 생성 중단 토큰 목록 |
+
+---
+
+## 5. C ABI 직접 임베딩 (C/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.
+

termux_bitnet-1.0.0/README.md

@@ -0,0 +1,180 @@
+# 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.**
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Architecture](https://img.shields.io/badge/Core-Native%20C++17%20|%20NEON%20|%20DotProd-brightgreen.svg)]()
+[![Python SDK](https://img.shields.io/badge/Gateway-pip%20install%20termux--bitnet-blue.svg)]()
+[![Node.js SDK](https://img.shields.io/badge/Gateway-npm%20install%20termux--bitnet-red.svg)]()
+[![Platform](https://img.shields.io/badge/Platform-Android%20Termux%20|%20PRoot%20|%20Linux-orange.svg)]()
+
+---
+
+## 1. 아키텍처 철학: "Single C++ Core, Dual Thin Gateways"
+
+`termux-bitnet`은 **"연산과 텐서 제어의 모든 핵심(Heavy Lifting)은 오직 순수 C++ 단 한 곳에서만 수행하고, Python(`pip`)과 Node.js(`npm`)는 제로 오버헤드로 C++ 엔진에 진입하는 경량 입구(Thin Gateway / FFI Boundary) 역할만 수행한다"**는 글로벌 표준 오픈소스 AI 엔진 설계 원칙을 철저히 준수합니다.
+
+```mermaid
+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`)를 통해 원터치로 캐싱 및 구동할 수 있습니다:
+
+| Alias | 원본 저장소 및 모델 파일 | 파라미터 / 용량 | 특징 |
+|---|---|---|---|
+| `bitnet-2b` | `microsoft/bitnet-b1.58-2B-4T-gguf` | 2.4B / **1.13 GB** | Microsoft 공식 1.58-bit 플래그십 (모바일 권장) |
+| `bitnet-large` | `RichardErkhov/1bitLLM_-_bitnet_b1_58-large-gguf` | 0.7B / **404 MB** | 저사양 모바일/Termux 기기용 초경량 엔진 |
+| `bitnet-3b` | `Green-Sky/bitnet_b1_58-3B-GGUF` | 3.3B / **730 MB** | 대용량 고정밀 온디바이스 모델 |
+| `bitnet-3b-q4` | `RichardErkhov/1bitLLM_-_bitnet_b1_58-3B-gguf` | 3.3B / **1.83 GB** | Q4 양자화 고성능 3B 모델 |
+
+```bash
+# 모델 원터치 다운로드 (이어받기 지원)
+termux-bitnet download bitnet-2b
+```
+
+---
+
+## 3. 빠른 시작 (Quick Start)
+
+### 3.1 Python Gateway (`pip`)
+
+```bash
+# 설치
+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
+```
+
+```python
+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`)
+
+```bash
+# 설치
+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
+```
+
+```javascript
+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)
+
+| CLI Flag | Python (`BitNetConfig`) | Node.js (`BitNetOptions`) | C ABI (`bitnet_params_t`) | 기본값 | 설명 |
+|---|---|---|---|---|---|
+| `-m, --model` | `model_path` | `modelPath` | `model_path` | `""` | GGUF 모델 파일 경로 |
+| `-p, --prompt` | `prompt` | `prompt` | `prompt` | `""` | 입력 프롬프트 텍스트 |
+| `-t, --threads` | `n_threads` | `threads` | `n_threads` | `cores` | CPU 워커 스레드 수 |
+| `-c, --ctx-size` | `n_ctx` | `contextSize` | `n_ctx` | `2048` | KV Cache 컨텍스트 윈도우 크기 |
+| `-b, --batch-size`| `n_batch` | `batchSize` | `n_batch` | `512` | 프롬프트 평가 배치 크기 |
+| `-n, --n-predict` | `n_predict` | `maxTokens` | `n_predict` | `128` | 최대 생성 토큰 수 |
+| `--temp` | `temperature` | `temperature` | `temperature` | `0.7` | Softmax 온도 (0.0=Greedy) |
+| `--top-p` | `top_p` | `topP` | `top_p` | `0.95` | Nucleus Top-P 샘플링 |
+| `--top-k` | `top_k` | `topK` | `top_k` | `40` | Top-K 샘플링 컷오프 |
+| `--min-p` | `min_p` | `minP` | `min_p` | `0.05` | Min-P 상대 확률 컷오프 |
+| `--repeat-penalty`| `repeat_penalty` | `repeatPenalty` | `repeat_penalty` | `1.15` | 반복 토큰 억제 계수 |
+| `-s, --seed` | `seed` | `seed` | `seed` | `0` | 난수 시드 (0=무작위) |
+| `--system-prompt` | `system_prompt` | `systemPrompt` | `system_prompt` | `""` | 시스템 프롬프트 접두사 |
+| `-r, --stop` | `stop_tokens` | `stopTokens` | `stop_tokens` | `""` | 생성 중단 토큰 목록 |
+
+---
+
+## 5. C ABI 직접 임베딩 (C/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.
+

termux_bitnet-1.0.0/include/termux_bitnet.h

@@ -0,0 +1,145 @@
+/**
+ * @file termux_bitnet.h
+ * @brief C ABI Interface for BitNet 1.58-bit (i2_s) On-Device Inference Engine.
+ * @author uno-km (https://github.com/uno-km)
+ * @license Apache-2.0
+ */
+
+#ifndef TERMUX_BITNET_H
+#define TERMUX_BITNET_H
+
+#include <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#if defined(_WIN32)
+    #if defined(TERMUX_BITNET_EXPORTS)
+        #define BITNET_API __declspec(dllexport)
+    #else
+        #define BITNET_API __declspec(dllimport)
+    #endif
+#else
+    #define BITNET_API __attribute__((visibility("default")))
+#endif
+
+/** Opaque handle to the BitNet execution context. */
+typedef struct bitnet_context* bitnet_context_t;
+
+/** Inference configuration and sampling hyperparameters. */
+typedef struct {
+    const char* model_path;      /**< Absolute or relative path to .gguf model */
+    const char* system_prompt;   /**< System prompt prefix */
+    const char* stop_tokens;     /**< Comma-separated stop sequences (e.g. "<|end|>,</s>") */
+    int32_t n_threads;           /**< CPU worker threads (default: hardware core count) */
+    int32_t n_ctx;               /**< KV Cache context window length (default: 2048) */
+    int32_t n_batch;             /**< Prompt evaluation logical batch size (default: 512) */
+    int32_t n_ubatch;            /**< Physical micro-batch size (default: 512) */
+    int32_t n_predict;           /**< Maximum tokens to generate (default: 128) */
+    int32_t top_k;               /**< Top-K sampling cutoff (0 = disabled, default: 40) */
+    int32_t repeat_last_n;       /**< Number of previous tokens to consider for penalty (default: 64) */
+    int32_t n_gpu_layers;        /**< Number of layers to offload to GPU/NPU (default: 0) */
+    uint32_t seed;               /**< RNG seed for deterministic sampling (0 = random) */
+    float temperature;           /**< Softmax temperature (0.0 = deterministic greedy) */
+    float top_p;                 /**< Nucleus sampling threshold (default: 0.95) */
+    float min_p;                 /**< Min-P sampling cutoff relative to max prob (default: 0.05) */
+    float typical_p;             /**< Locally typical sampling threshold (default: 1.0) */
+    float repeat_penalty;        /**< Repetition penalty coefficient (default: 1.15) */
+    float frequency_penalty;     /**< Frequency penalty coefficient (default: 0.0) */
+    float presence_penalty;      /**< Presence penalty coefficient (default: 0.0) */
+    bool flash_attn;             /**< Enable flash attention acceleration (default: false) */
+    bool verbose;                /**< Enable verbose diagnostic logs */
+} bitnet_params_t;
+
+/** Token generation callback for streaming responses. Return false to abort early. */
+typedef bool (*bitnet_stream_cb)(const char* token_str, int32_t token_id, void* user_data);
+
+/**
+ * @brief Initialize default hyperparameters.
+ */
+BITNET_API bitnet_params_t bitnet_default_params(void);
+
+/**
+ * @brief Load a 1.58-bit GGUF model and initialize the execution engine.
+ * @param params Pointer to engine parameters.
+ * @return Context handle on success, NULL on failure.
+ */
+BITNET_API bitnet_context_t bitnet_init(const bitnet_params_t* params);
+
+/**
+ * @brief Release all memory, KV cache, and model weights associated with the context.
+ * @param ctx Context handle.
+ */
+BITNET_API void bitnet_free(bitnet_context_t ctx);
+
+/**
+ * @brief Tokenize an input string into token IDs.
+ * @param ctx Context handle.
+ * @param text UTF-8 input string.
+ * @param tokens Output buffer for token IDs.
+ * @param max_tokens Maximum size of the output buffer.
+ * @return Number of tokens generated, or negative error code.
+ */
+BITNET_API int32_t bitnet_tokenize(bitnet_context_t ctx, const char* text, int32_t* tokens, int32_t max_tokens);
+
+/**
+ * @brief Convert a token ID to its UTF-8 string representation.
+ * @param ctx Context handle.
+ * @param token Token ID.
+ * @param buf Output string buffer.
+ * @param buf_len Buffer capacity.
+ * @return Number of characters written.
+ */
+BITNET_API int32_t bitnet_token_to_str(bitnet_context_t ctx, int32_t token, char* buf, int32_t buf_len);
+
+/**
+ * @brief Perform forward evaluation of a token sequence into the KV cache.
+ * @param ctx Context handle.
+ * @param tokens Array of token IDs.
+ * @param n_tokens Number of tokens to evaluate.
+ * @return 0 on success, non-zero on error.
+ */
+BITNET_API int32_t bitnet_eval(bitnet_context_t ctx, const int32_t* tokens, int32_t n_tokens);
+
+/**
+ * @brief Sample the next token from current logits using configured temperature & top_p.
+ * @param ctx Context handle.
+ * @return Sampled token ID.
+ */
+BITNET_API int32_t bitnet_sample(bitnet_context_t ctx);
+
+/**
+ * @brief High-level streaming text generation interface.
+ * @param ctx Context handle.
+ * @param prompt Input prompt text.
+ * @param max_new_tokens Maximum number of tokens to generate.
+ * @param callback Callback invoked on each generated token piece.
+ * @param user_data User-defined pointer passed to callback.
+ * @return Total number of tokens generated.
+ */
+BITNET_API int32_t bitnet_generate_stream(bitnet_context_t ctx, const char* prompt, int32_t max_new_tokens, bitnet_stream_cb callback, void* user_data);
+
+/**
+ * @brief Inspect runtime hardware features and acceleration modes.
+ * @param buf Output buffer.
+ * @param buf_len Buffer capacity.
+ */
+BITNET_API void bitnet_get_hardware_info(char* buf, int32_t buf_len);
+
+/**
+ * @brief Retrieve performance metrics of the last generation.
+ * @param ctx Context handle.
+ * @param prompt_eval_ms Output pointer for TTFT / prompt eval time in ms.
+ * @param eval_ms Output pointer for token generation eval time in ms.
+ * @param tokens_per_sec Output pointer for generation tokens/sec.
+ */
+BITNET_API void bitnet_get_perf_stats(bitnet_context_t ctx, double* prompt_eval_ms, double* eval_ms, double* tokens_per_sec);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* TERMUX_BITNET_H */

termux_bitnet-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel", "cmake>=3.20.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "termux-bitnet"
+version = "1.0.0"
+description = "High-performance 1.58-bit BitNet inference engine, Python SDK & CLI optimized for Android Termux and ARM64 architecture."
+readme = "README.md"
+authors = [
+    { name = "uno-km", email = "unokim.dev@gmail.com" }
+]
+license = { text = "Apache-2.0" }
+keywords = ["bitnet", "1-bit-llm", "termux", "arm64", "neon", "dotprod", "edge-ai", "on-device-ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: C++",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: Android",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "tqdm>=4.64.0",
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+server = [
+    "uvicorn>=0.20.0",
+    "fastapi>=0.95.0",
+]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-benchmark>=4.0.0",
+]
+
+[project.scripts]
+termux-bitnet = "termux_bitnet.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/uno-km/termux-bitnet"
+Documentation = "https://uno-km.github.io/termux-bitnet/"
+Repository = "https://github.com/uno-km/termux-bitnet.git"
+Issues = "https://github.com/uno-km/termux-bitnet/issues"