Termux-AIChain

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

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		Zero-Dependency Multimodal Agent Chaining & StateGraph Engine (Python stdlib + Node.js ESM)	Docs
🎙️ termux-stt		Integrated On-Device STT & Pure Python 128d X-Vector Diarization (Whisper + Vosk + Sherpa)	Docs
🎨 termux-diffusion		Mobile On-Device Stable Diffusion Image Generation (bfloat16 ARM NEON acceleration)	Docs
🌐 termux-playwright		Non-Root Native Headless Chromium Browser Automation & Scraping	Docs
🧠 termux-train		Mobile Native Autograd Neural Network Training & LoRA Fine-Tuning	Docs
⚡ AMEVA-Forge		High-Performance WebGPU Autograd & 3D Neural Studio Engine	Docs

1. Quick Installation

1-Line Bootstrap Script (Android Termux)

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

Python SDK (PyPI):

pip install --upgrade termux-aichain

Node.js / TypeScript SDK (npm):

npm install termux-aichain

CLI One-Touch Environment Verification:

# 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

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

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

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

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)

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

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)

8 Sampling Control Parameters (OpenAICompatibleChat / BitNetChat)

5. Empirical Benchmarks (Galaxy S20)

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

6. License & Compliance

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