Metadata-Version: 2.4
Name: termux-aichain
Version: 1.0.4
Summary: Sovereign Zero-Dependency AI Chaining and Multimodal Autonomous Agent Framework for Android Edge and Termux
Home-page: https://github.com/uno-km/termux-aichain
Author: UnoKim
Author-email: UnoKim <uno-km@users.noreply.github.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/uno-km/termux-aichain
Project-URL: Repository, https://github.com/uno-km/termux-aichain.git
Project-URL: Issues, https://github.com/uno-km/termux-aichain/issues
Keywords: termux,android,edge-ai,langchain,llama-cpp,bitnet,agent,zero-dependency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Android
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Termux-AIChain

<div align="center">

```
 ████████╗███████╗██████╗ ███╗   ███╗██╗   ██╗██╗  ██╗       █████╗ ██╗ ██████╗██╗  ██╗ █████╗ ██╗███╗   ██╗
 ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║   ██║╚██╗██╔╝      ██╔══██╗██║██╔════╝██║  ██║██╔══██╗██║████╗  ██║
    ██║   █████╗  ██████╔╝██╔████╔██║██║   ██║ ╚███╔╝ █████╗███████║██║██║     ███████║███████║██║██╔██╗ ██║
    ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║   ██║ ██╔██╗ ╚════╝██╔══██║██║██║     ██╔══██║██╔══██║██║██║╚██╗██║
    ██║   ███████╗██║  ██║██║ ╚═╝ ██║╚██████╔╝██╔╝ ██╗      ██║  ██║██║╚██████╗██║  ██║██║  ██║██║██║ ╚████║
    ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝      ╚═╝  ╚═╝╚═╝ ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝
```

**Sovereign Zero-Dependency AI Chaining & Multimodal Autonomous Agent Framework for Android Termux**  
*Dual-Engine Architecture (Pure Python 3.10+ Stdlib & Pure Node.js 18+ ESM) with Native ARM64 Acceleration & 0 Heavy External Dependency*

<p align="center">
  <a href="https://pypi.org/project/termux-aichain/"><img src="https://img.shields.io/pypi/v/termux-aichain.svg?style=for-the-badge&color=0088ff&logo=pypi&logoColor=white" alt="PyPI Version" /></a>
  <a href="https://pypi.org/project/termux-aichain/"><img src="https://img.shields.io/badge/PyPI%20Downloads-active-0088ff?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI Downloads" /></a>
  <a href="https://www.npmjs.com/package/termux-aichain"><img src="https://img.shields.io/npm/v/termux-aichain.svg?style=for-the-badge&color=cb3837&logo=npm&logoColor=white" alt="npm Version" /></a>
  <a href="https://www.npmjs.com/package/termux-aichain"><img src="https://img.shields.io/badge/npm%20Downloads-active-cb3837?style=for-the-badge&logo=npm&logoColor=white" alt="npm Downloads" /></a>
</p>

<p align="center">
  <a href="https://uno-km.vercel.app/lib/aichain/"><img src="https://img.shields.io/badge/Official_Docs-uno--km.vercel.app%2Flib%2Faichain-004499?style=for-the-badge&logo=vercel&logoColor=white" alt="Live Docs" /></a>
  <a href="https://github.com/uno-km/termux-aichain"><img src="https://img.shields.io/github/stars/uno-km/termux-aichain?style=for-the-badge&color=gold&logo=github" alt="GitHub Stars" /></a>
  <a href="https://github.com/uno-km/termux-aichain/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="License" /></a>
  <a href="https://github.com/uno-km/termux-aichain"><img src="https://img.shields.io/badge/Tests-73%2F73%20PASS-success.svg?style=for-the-badge" alt="Tests" /></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Platform-Android%20Termux%20(ARM64%2Faarch64)-00887A?style=flat-square&logo=android&logoColor=white" alt="Platform" />
  <img src="https://img.shields.io/badge/Dependencies-0%20External%20Packages-success.svg?style=flat-square" alt="Zero Dep" />
  <img src="https://img.shields.io/badge/Cold%20Start-12.8ms-brightgreen?style=flat-square" alt="Cold Start" />
  <img src="https://img.shields.io/badge/RAM-14.2MB%20RSS-blue?style=flat-square" alt="RAM" />
  <img src="https://img.shields.io/badge/Foundation-AOSF_Tier_1-orange?style=flat-square" alt="Foundation" />
</p>

<br/>

**[Official Documentation Site](https://uno-km.vercel.app/lib/aichain/)** · **[AMEVA Foundation](https://uno-km.vercel.app/foundation/)** · **[Installation](#1-quick-installation)** · **[Architecture](#2-why-termux-aichain-architectural-pillars)** · **[Recipes & Manual](#3-comprehensive-usage-recipes--manual)** · **[Parameters](#4-hardware-tuning--sampling-parameters)** · **[Benchmarks](#5-empirical-benchmarks-galaxy-s20)**

</div>

---

## AMEVA Foundation — Sovereign Mobile AI Ecosystem

> **"$0 Cloud Cost, 0% External Data Egress. Turning every Android smartphone into a sovereign autonomous AI workstation."**  
> The **AMEVA Open-Source Foundation (AOSF)** builds next-generation, client-centric AI runtimes spanning on-device large models, browser automation, neural network training, speech-to-text, and autonomous agent chaining.

| Project | Platform & Packages | Core Capability & Technology | Documentation |
| :--- | :--- | :--- | :---: |
| ⚡ **[termux-aichain](https://github.com/uno-km/termux-aichain)** | [![PyPI](https://img.shields.io/pypi/v/termux-aichain?color=blue&style=flat-square)](https://pypi.org/project/termux-aichain/) [![npm](https://img.shields.io/npm/v/termux-aichain?color=red&style=flat-square)](https://www.npmjs.com/package/termux-aichain) | **Zero-Dependency Multimodal Agent Chaining & StateGraph Engine** (Python stdlib + Node.js ESM) | **[Docs](https://uno-km.vercel.app/lib/aichain/)** |
| 🎙️ **[termux-stt](https://github.com/uno-km/termux-stt)** | [![PyPI](https://img.shields.io/pypi/v/termux-stt?color=blue&style=flat-square)](https://pypi.org/project/termux-stt/) [![npm](https://img.shields.io/npm/v/termux-stt?color=red&style=flat-square)](https://www.npmjs.com/package/termux-stt) | **Integrated On-Device STT & Pure Python 128d X-Vector Diarization** (Whisper + Vosk + Sherpa) | **[Docs](https://uno-km.vercel.app/lib/stt/)** |
| 🎨 **[termux-diffusion](https://github.com/uno-km/termux-diffusion)** | [![PyPI](https://img.shields.io/pypi/v/termux-diffusion?color=blue&style=flat-square)](https://pypi.org/project/termux-diffusion/) [![npm](https://img.shields.io/npm/v/termux-diffusion?color=red&style=flat-square)](https://www.npmjs.com/package/termux-diffusion) | **Mobile On-Device Stable Diffusion Image Generation** (bfloat16 ARM NEON acceleration) | **[Docs](https://uno-km.vercel.app/lib/diffusion/)** |
| 🌐 **[termux-playwright](https://github.com/uno-km/termux-playwright)** | [![PyPI](https://img.shields.io/pypi/v/termux-playwright?color=blue&style=flat-square)](https://pypi.org/project/termux-playwright/) [![npm](https://img.shields.io/npm/v/termux-playwright?color=red&style=flat-square)](https://www.npmjs.com/package/termux-playwright) | **Non-Root Native Headless Chromium Browser Automation & Scraping** | **[Docs](https://uno-km.vercel.app/lib/playwright/)** |
| 🧠 **[termux-train](https://github.com/uno-km/termux-train)** | [![PyPI](https://img.shields.io/pypi/v/termux-train.svg?color=blue&style=flat-square)](https://pypi.org/project/termux-train/) | **Mobile Native Autograd Neural Network Training & LoRA Fine-Tuning** | **[Docs](https://uno-km.vercel.app/lib/train/)** |
| ⚡ **[AMEVA-Forge](https://github.com/uno-km/ameva-forge)** | [![WebGPU](https://img.shields.io/badge/WebGPU-Autograd-purple?style=flat-square)](https://uno-km.vercel.app/lib/forge/) | **High-Performance WebGPU Autograd & 3D Neural Studio Engine** | **[Docs](https://uno-km.vercel.app/lib/forge/)** |

---

## 1. Quick Installation

### 1-Line Bootstrap Script (Android Termux)

```bash
curl -sSL https://raw.githubusercontent.com/uno-km/termux-aichain/main/scripts/install.sh | bash
```

### Python SDK (PyPI):

```bash
pip install --upgrade termux-aichain
```

### Node.js / TypeScript SDK (npm):

```bash
npm install termux-aichain
```

### CLI One-Touch Environment Verification:

```bash
# Verify Bionic ARM64 environment, Termux APIs, and engine binaries
termux-aichain setup

# Pull verified GGUF model checkpoint (Llama-3.2-3B, Qwen-2.5-1.5B, BitNet-3B)
termux-aichain pull qwen-2.5-1.5b

# Start 1-line REST, SSE streaming server and Web Dashboard on port 8080
termux-aichain serve --port 8080
```

---

## 2. Why Termux-AIChain? Architectural Pillars

### 1. Zero-Heavy-Dependency Doctrine
- Standard edge AI libraries (LangChain, LlamaIndex, CrewAI) introduce 40~80 heavy dependencies (Pydantic, NumPy, aiohttp, requests, tenacity), resulting in 200MB+ memory baselines and frequent C-compilation failures on Android Bionic ARM64.
- `termux-aichain` is written strictly with the **Python 3.10+ Standard Library** (`urllib`, `sqlite3`, `subprocess`, `json`, `math`, `typing`, `http.server`) and **Pure Node.js 18+ ESM** (`http`, `node:sqlite`, `node:test`).
- **Cold start import latency is 12.8ms**, and total package disk footprint is under **268KB**.

### 2. Native StateGraph & ReAct Engine
- Deterministic cyclic state machines with entry points, explicit edges, conditional routing, and `max_iterations` recursion safety limits.
- Built-in `create_react_agent` factory for autonomous tool-calling loops without heavy orchestrator overhead.

### 3. Full-Spectrum Local Server Hardware Fine-Tuning
- Direct lifecycle management and parameter injection for `llama-server` and `BitNet.cpp`.
- 12 hardware flags exposed: `threads`, `n_ctx`, `n_batch`, `n_ubatch`, `n_gpu_layers`, `flash_attn`, `cache_type_k` (q8_0/q4_0), `cache_type_v`, `mlock`, `cont_batching`, `rope_freq_scale`.

### 4. SQLite ACID Long-Term Memory & Pure Cosine Vector RAG
- Persistent entity key-value storage and vector similarity search built on native SQLite.
- Pure Python and Pure JavaScript algebraic vector dot product and cosine normalization without ChromaDB or NumPy.

### 5. Native Android Hardware Actuation & Ecosystem Integration
- Built-in tool wrappers for Termux:API (`battery`, `sensor`, `gps`, `vibrate`, `notification`, `tts`, `shell`).
- Three-tier fallback: Automatically queries `/sys/class/power_supply/battery` and `/sys/devices/virtual/thermal` directly from kernel sysfs if `termux-api` is absent.
- Direct ecosystem hooks for `termux-stt` (voice STT), `termux-diffusion` (image rendering), and `termux-playwright` (headless web scraping).

---

## 3. Comprehensive Usage Recipes & Manual

### Recipe 1: 1-Line Local LLM / BitNet LCEL Pipe Chaining

```python
from termux_aichain import PromptTemplate, JsonOutputParser, OpenAICompatibleChat

# 1. Define prompt template and JSON output parser
prompt = PromptTemplate.from_template(
    "Extract structured system status from log:
{log}
Respond in JSON with fields 'level', 'code', 'message'."
)
parser = JsonOutputParser()

# 2. Connect to local llama-server / BitNet endpoint
llm = OpenAICompatibleChat(base_url="http://127.0.0.1:8080/v1", temperature=0.1)

# 3. Assemble LCEL pipe chain
chain = prompt | llm | parser

# 4. Execute synchronously
result = chain.invoke({"log": "CRITICAL: Kernel thermal throttling triggered at 48C (Code 104)"})
print("Parsed JSON Result:", result)
```

### Recipe 2: Autonomous ReAct Multi-Agent with StateGraph

```python
from termux_aichain import (
    create_react_agent,
    BitNetChat,
    HumanMessage,
    get_battery_status,
    vibrate_device,
    transcribe_speech
)

# 1. Initialize local brain
model = BitNetChat(base_url="http://127.0.0.1:8080/v1", temperature=0.1)

# 2. Construct autonomous ReAct agent with hardware tools
agent = create_react_agent(
    model=model,
    tools=[get_battery_status, transcribe_speech, vibrate_device],
    system_prompt="You are a sovereign mobile agent running on Android Termux."
)

# 3. Execute multi-step reasoning and acting loop
state = agent.invoke({
    "messages": [HumanMessage(content="Check battery percentage and vibrate device for 500ms if battery > 50%.")]
})

print("Agent Final Response:", state["messages"][-1].content)
```

### Recipe 3: SQLite Long-Term Memory & Cosine Vector Store

```python
from termux_aichain import SQLiteEntityMemory, SQLiteVectorStore

# 1. Persistent Key-Value Entity Memory
memory = SQLiteEntityMemory(db_path="mobile_agent.db")
memory.save_entity("device_owner", "Dr. Uno Kim")
memory.save_entity("preferred_model", "BitNet-3B-1.58b")

print("Retrieved Owner:", memory.get_entity("device_owner"))

# 2. Pure Cosine Vector Store (No NumPy / ChromaDB needed)
vector_store = SQLiteVectorStore(db_path="vector_rag.db")
vector_store.add_texts(
    texts=["Android Bionic Subsystem Architecture", "WebGPU Neural Compute Shaders"],
    embeddings=[[0.92, 0.38, 0.05], [0.12, 0.44, 0.89]],
    metadatas=[{"source": "os_doc"}, {"source": "gpu_doc"}]
)

matches = vector_store.similarity_search_by_vector([0.90, 0.40, 0.00], k=1)
print("Top RAG Match:", matches[0].page_content, f"(Score: {matches[0].score:.4f})")
```

### Recipe 4: 1-Line REST, SSE Streaming Server & Web Dashboard

```python
from termux_aichain import create_react_agent, OpenAICompatibleChat, serve, get_battery_status

llm = OpenAICompatibleChat(base_url="http://127.0.0.1:8080/v1")
agent = create_react_agent(model=llm, tools=[get_battery_status])

# Starts REST API (POST /v1/agent/invoke, POST /v1/agent/stream) and Web Dashboard UI
serve(agent, host="0.0.0.0", port=8000)
```

### Recipe 5: Full Multimodal Pipeline (STT + Diffusion + Playwright + Haptic)

```python
from termux_aichain import (
    create_react_agent,
    BitNetChat,
    HumanMessage,
    get_battery_status,
    transcribe_speech,
    generate_diffusion_image,
    browse_web_headless,
    vibrate_device
)

llm = BitNetChat(base_url="http://127.0.0.1:8080/v1", temperature=0.1)

agent = create_react_agent(
    model=llm,
    tools=[
        get_battery_status,
        transcribe_speech,
        generate_diffusion_image,
        browse_web_headless,
        vibrate_device
    ],
    system_prompt="You are a multimodal autonomous edge agent capable of speech, image, web scraping, and device control."
)

state = agent.invoke({
    "messages": [HumanMessage(content="Transcribe speech from meeting.wav, search local weather, generate an emblem image, and vibrate.")]
})
```

### Recipe 6: Node.js ESM Native Autonomous Agent

```javascript
import {
  PromptTemplate,
  JsonOutputParser,
  OpenAICompatibleChat,
  StateGraph,
  START,
  END,
  MicroVectorStore,
  getDefaultDeviceTools
} from "termux-aichain";

// 1. In-Memory Micro Vector Store
const vectorStore = new MicroVectorStore();
vectorStore.addTexts(
  ["Linux Kernel Bionic", "ARM NEON SIMD"],
  [[1.0, 0.0], [0.0, 1.0]]
);

const matches = vectorStore.similaritySearchByVector([0.98, 0.02], 1);
console.log("Vector Match:", matches[0].content, `(Score: ${matches[0].score.toFixed(4)})`);

// 2. Cyclic StateGraph Compilation
const workflow = new StateGraph();
workflow.addNode("counter", (state) => ({ step: (state.step || 0) + 1 }));
workflow.setEntryPoint("counter");
workflow.addConditionalEdges("counter", (state) => (state.step >= 3 ? END : "counter"));

const app = workflow.compile();
const result = await app.invoke({ step: 0 });
console.log("Graph Execution Result:", result);
```

---

## 4. Hardware Tuning & Sampling Parameters

### 12 Hardware Tuning Flags (`LocalServerConfig`)

| Parameter | Type | Default | Valid Range | Technical Function |
| :--- | :---: | :---: | :---: | :--- |
| `threads` | `int` | `CPU-1` | `1 ~ 16` | Number of dedicated CPU threads for BLAS/NEON computation. |
| `n_ctx` | `int` | `2048` | `512 ~ 32768` | Total token capacity allocated for the model context window. |
| `n_batch` | `int` | `512` | `32 ~ 2048` | Prompt evaluation batch size. |
| `n_ubatch` | `int` | `256` | `16 ~ 512` | Micro-batch size for strictly memory-constrained edge hardware. |
| `n_gpu_layers` | `int` | `0` | `0 ~ 99` | Number of model layers offloaded to Vulkan / OpenCL / GPU compute. |
| `flash_attn` | `bool` | `False` | `True / False` | Flash Attention kernel acceleration toggle (`-fa`). |
| `cache_type_k` | `str` | `"f16"` | `"f16"`, `"q8_0"`, `"q4_0"` | Key cache quantization format (q8_0 saves 50% RAM, q4_0 saves 75%). |
| `cache_type_v` | `str` | `"f16"` | `"f16"`, `"q8_0"`, `"q4_0"` | Value cache quantization format. |
| `mlock` | `bool` | `False` | `True / False` | Lock model weights in RAM to prevent disk swapping. |
| `cont_batching` | `bool` | `True` | `True / False` | Continuous batching support for multi-turn conversations. |
| `rope_freq_scale` | `float` | `None` | `0.1 ~ 1.0` | Linear RoPE context extension factor. |
| `port` | `int` | `8080` | `1024 ~ 65535` | Local TCP port for the model server. |

### 8 Sampling Control Parameters (`OpenAICompatibleChat` / `BitNetChat`)

| Parameter | Type | Default | Valid Range | Technical Description |
| :--- | :---: | :---: | :---: | :--- |
| `temperature` | `float` | `0.7` | `0.0 ~ 2.0` | Nucleus generation randomness (0.0 for deterministic code/JSON). |
| `top_p` | `float` | `0.95` | `0.0 ~ 1.0` | Cumulative probability cutoff threshold for candidate token filtering. |
| `top_k` | `int` | `40` | `1 ~ 100` | Integer limit on candidate token selection pool. |
| `min_p` | `float` | `0.05` | `0.0 ~ 1.0` | Minimum relative probability cutoff to eliminate low-rank hallucinations. |
| `repeat_penalty` | `float` | `1.1` | `1.0 ~ 2.0` | Frequency penalty scale to avoid infinite token repetition loops. |
| `stop` | `List[str]` | `None` | `List[str]` | Generation termination sequence delimiters. |
| `seed` | `int` | `None` | `int` | Random seed for exact deterministic generation reproducibility. |
| `grammar` | `str` | `None` | `str` | GBNF or Regex structural constraint schema for forced JSON output. |

---

## 5. Empirical Benchmarks (Galaxy S20)

Measured on physical mobile hardware (Samsung Galaxy S20 5G, Qualcomm Snapdragon 865, 12GB RAM, Android 13 Termux):

| Measurement Metric | LangChain (Heavyweight) | `termux-aichain` v1.0.2 | Performance Delta |
| :--- | :---: | :---: | :---: |
| **Cold Start Import Latency** | 1,240.0 ms | **12.8 ms** | **96.8x Faster** |
| **Baseline RAM Footprint (RSS)** | 185.0 MB | **14.2 MB** | **92.3% Memory Saved** |
| **Package Disk Size** | 48.5 MB | **0.26 MB (268 KB)** | **99.4% Disk Saved** |
| **External Dependencies** | 42+ packages | **0 packages** | **Zero External Dependencies** |
| **5-Step Multimodal E2E Run** | Failed (Crash) | **46.4 ms** | **100% Deterministic PASS** |
| **Unit Test Suite Coverage** | Variable | **73 / 73 PASS (100%)** | **Zero-Defect Verification** |

---

## 6. License & Compliance

- **License**: Apache License 2.0 (`Apache-2.0`).
- **Official Documentation Portal**: [https://uno-km.vercel.app/lib/aichain/](https://uno-km.vercel.app/lib/aichain/)
- **GitHub Repository**: [https://github.com/uno-km/termux-aichain](https://github.com/uno-km/termux-aichain)
- **AMEVA Open-Source Foundation (AOSF)**.
