Termux-AIChain

 _____                                     ___  _____ _____ _           _       
|_   _|                                   / _ \|_   _/  __ \ |         (_)      
  | | ___ _ __ _ __ ___  _   ___  __     / /_\ \ | | | /  \/ |__   __ _ _ _ __  
  | |/ _ \ '__| '_ ` _ \| | | \ \/ / ___ |  _  | | | | |   | '_ \ / _` | | '_ \ 
  | |  __/ |  | | | | | | |_| |>  < |___|| | | |_| |_| \__/\ | | | (_| | | | | |
  \_/\___|_|  |_| |_| |_|\__,_/_/\_\     \_| |_/\___/ \____/_| |_|\__,_|_|_| |_|

🚀 Why termux-aichain Instead of LangChain on Termux & Edge?

Running standard desktop AI frameworks like LangChain, LlamaIndex, or CrewAI inside an Android Termux (Bionic libc / ARM64) environment is notoriously fragile, resource-exhausting, and often impossible.

termux-aichain is purpose-built from ground zero to replace bloated desktop frameworks with an ultra-lightweight, zero-external-dependency, edge-native engine that delivers full LCEL pipe compatibility (prompt | llm | parser), StateGraph multi-agent execution, and native Android smartphone actuation.

Comprehensive Head-to-Head Comparison

5 Fatal Flaws of Running LangChain on Mobile (and How termux-aichain Solves Them)

1. The Native Wheel & Rust Compilation Barrier: LangChain requires pydantic-core, chromadb, and tiktoken. On Android Termux, prebuilt wheels are rarely published for the Android Bionic C runtime. Users are forced to spend hours installing clang, binutils, and rustc, which frequently crash due to memory exhaustion during compilation. termux-aichain is written in 100% pure Python standard library and Node.js standard modules. No compiler is ever invoked.

2. Android Low Memory Killer (LMK) Aggression: When loading a 1B~3B LLM (e.g., Llama-3.2 1B occupying ~800MB RAM), the phone's memory margin is thin. LangChain's idle overhead of 180MB+ pushes total process memory past the Android foreground limit, triggering instant SIGKILL by the kernel. termux-aichain has a baseline RSS footprint of only 14.2MB, granting virtually the entire memory budget to model weights.

3. Subprocess & Mobile API Impedance Mismatch: Desktop agent frameworks expect cloud API keys (OpenAI, Anthropic) or desktop Docker daemons. They have zero awareness of mobile power management, Android battery states, or thermal throttling. termux-aichain provides hardware-native sensor tools (get_battery_status, get_sensor_data, vibrate_device, send_notification) as native first-class functions.

4. Import Latency in Ephemeral CLI Runs: Running a command-line utility with LangChain requires waiting 3 to 7 seconds just for Python to finish importing modules before the first line of code executes. termux-aichain imports in 12.8ms using lazy import tables.

5. Serverless Vector RAG Without Heavy External Engines: Setting up FAISS or ChromaDB in Termux requires C++ compilers and large shared libraries. termux-aichain includes SQLiteVectorStore, utilizing the standard library sqlite3 and pure-math cosine similarity.

🐍 Python Quickstart

Installation

# In Termux or Linux (Python 3.10+):
pip install --upgrade termux-aichain

1-Line Hello Agent (Local llama-server / OpenAI-Compatible)

from termux_aichain import LocalAgent

# Connects directly to local llama-server (127.0.0.1:8080) or BitNet
agent = LocalAgent.local(model="llama3")
response = agent.run("Hello! Introduce yourself in one short sentence.")
print(response)

🟩 Node.js / TypeScript Quickstart

Installation

# In Termux or Node.js (v18+ ESM):
npm install termux-aichain

1-Line Hello Agent (ESM)

import { LocalAgent } from "termux-aichain";

// Connects directly to local llama-server (127.0.0.1:8080)
const agent = await LocalAgent.local("llama3");
const response = await agent.run("Hello! Introduce yourself in one short sentence.");
console.log(response);

🧩 LCEL Pipeline Recipes (LangChain Expression Language)

termux-aichain implements the full Runnable Protocol, allowing arbitrary chaining using the pipe operator (|).

Recipe 1: PromptTemplate | Model | StringOutputParser

from termux_aichain import PromptTemplate, OpenAICompatibleChat, StringOutputParser

# 1. Define prompt with variables
prompt = PromptTemplate.from_template(
    "You are an on-device AI running on Android. Explain {concept} in one crisp sentence."
)

# 2. Bind to local inference server (port 8080)
llm = OpenAICompatibleChat(
    base_url="http://127.0.0.1:8080/v1",
    model="llama3",
    temperature=0.3,
    max_tokens=64
)

# 3. Assemble LCEL chain
chain = prompt | llm | StringOutputParser()

# 4. Invoke synchronously
result = chain.invoke({"concept": "edge computing"})
print("Result:", result)

Recipe 2: Streaming Token Generation with Real-Time Telemetry

from termux_aichain import OpenAICompatibleChat, HumanMessage, SystemMessage

llm = OpenAICompatibleChat(base_url="http://127.0.0.1:8080/v1", model="llama3")

messages = [
    SystemMessage(content="You are a sovereign mobile assistant."),
    HumanMessage(content="Write a 3-bullet summary of edge AI benefits.")
]

# Real-time token streaming with zero memory accumulation
for chunk in llm.stream(messages):
    print(chunk.content, end="", flush=True)
print()

🤖 Autonomous ReAct Agent with Android Hardware Actuation

Agents can observe real physical hardware metrics (battery percentage, device temperature, charging status) and actuate physical outputs (vibrate, notification, sound).

import json
from termux_aichain import (
    create_react_agent,
    OpenAICompatibleChat,
    HumanMessage,
    get_battery_status,
    vibrate_device,
    send_notification
)

# 1. Initialize local LLM
llm = OpenAICompatibleChat(base_url="http://127.0.0.1:8080/v1", model="llama3")

# 2. Create ReAct agent with native Android hardware tools
agent = create_react_agent(
    model=llm,
    tools=[get_battery_status, vibrate_device, send_notification],
    system_prompt="You are an autonomous smartphone agent. Inspect device sensors and take action when requested."
)

# 3. Execute reasoning-and-acting loop
result = agent.invoke({
    "messages": [
        HumanMessage(content="Check my phone battery. If temperature is below 35C, vibrate the device for 300ms.")
    ]
})

print("Agent Diagnostic:", result["messages"][-1].content)

🗄️ Zero-Dependency On-Device SQLite Vector Store (RAG)

Store embeddings and perform semantic cosine similarity search directly inside mobile SQLite without installing ChromaDB, FAISS, or C++ dependencies.

from termux_aichain import SQLiteVectorStore

# 1. Initialize vector store in memory or local file ('knowledge.db')
vector_store = SQLiteVectorStore(":memory:")

# 2. Add documents with pre-computed or local embeddings
documents = [
    "Galaxy S25 acts as the Master Coordinator running llama-server on port 8080.",
    "Galaxy A53 acts as the Dedicated Speech Worker running neural TTS on port 8088.",
    "The AMEVA ecosystem executes sovereign edge inference with zero cloud egress."
]

# 4-dimensional sample vectors
vectors = [
    [1.0, 0.2, 0.0, 0.0],
    [0.0, 1.0, 0.2, 0.0],
    [0.1, 0.1, 1.0, 0.0]
]

vector_store.add_texts(documents, vectors, metadatas=[{"node": "s25"}, {"node": "a53"}, {"node": "ameva"}])

# 3. Query by vector (Finds Speech Worker document with highest cosine similarity)
query_vec = [0.0, 0.95, 0.1, 0.0]
matches = vector_store.similarity_search_by_vector(query_vec, k=1)

print("Retrieved Document:", matches[0].page_content)
# Output: "Galaxy A53 acts as the Dedicated Speech Worker running neural TTS on port 8088."

📱 Android Hardware Actuation Tools (First-Class Citizens)

All tools run with strict JSON schema validation, timeout protection, and fail-safe fallbacks.

🛠️ Hardware Tuning & Sampling Parameters

Local Server Configuration (LocalServerConfig)

from termux_aichain import LocalServerConfig, LocalServerManager

config = LocalServerConfig(
    model_path="/data/data/com.termux/files/home/models/llama-3.2-1b.gguf",
    threads=8,            # CPU computation threads (Oryon / Cortex-X)
    n_ctx=2048,           # Context window length
    n_batch=512,          # Prompt evaluation batch size
    n_ubatch=256,         # Micro-batch size for constrained mobile RAM
    n_gpu_layers=0,       # 0 for CPU, 99 for Adreno/Mali GPU offload
    port=8080,            # HTTP listening port
    flash_attn=False,     # Flash Attention toggle
    cache_type_k="f16",   # Key cache quantization ("f16", "q8_0", "q4_0")
    cache_type_v="f16",   # Value cache quantization
    mlock=False           # Lock model memory to prevent disk thrashing
)

Sampling Parameters (OpenAICompatibleChat / BitNetChat)

📊 Physical Real-Device Benchmarks (Galaxy S25 & A53)

Measured on actual hardware (Samsung Galaxy S25 Snapdragon 8 Elite / Galaxy A53 Exynos 1280):

🔒 Security Architecture: Default-Deny Tool Policy

termux-aichain implements strict zero-trust security for mobile hardware actuation:

from termux_aichain import ToolPolicy, ToolRule

# Default-deny security policy
policy = ToolPolicy(
    default="deny",
    rules=[
        ToolRule(name="get_battery_status", allow=True),
        ToolRule(name="vibrate_device", allow=True, max_calls_per_minute=10),
        ToolRule(name="execute_shell", allow=False)  # Explicitly forbidden
    ]
)

📜 Official Ecosystem & Links

• Official Web Documentation: https://uno-km.vercel.app/lib/aichain/
• PyPI Registry: https://pypi.org/project/termux-aichain/
• npm Registry: https://www.npmjs.com/package/termux-aichain
• GitHub Repository: https://github.com/uno-km/termux-aichain
• AMEVA Open-Source Foundation (AOSF)

📄 License

Licensed under the Apache License, Version 2.0 (Apache-2.0). Copyright (c) 2026 Eunho Kim (@uno-km).