termux-aichain

v1.1.0

Published

16 hours ago

Sovereign zero-dependency AI chaining and multimodal autonomous agent framework for Node.js ESM and Android Termux.

0High
0Medium
0Low

uno-km

termux android edge-ai langchain llama-cpp bitnet agent zero-dependency state-graph react-agent multimodal

Termux-AIChain

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

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

Official Documentation Site • AMEVA Foundation • Python Guide • Node.js Guide • Termux Setup • 10 Copy-Paste Recipes • Hardware Tuning • Benchmarks

🌐 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.

⚡ 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. Dual-Engine Native Parity (Python Stdlib + Node.js ESM)

100% equivalent API contracts between Python and JavaScript/TypeScript: LocalAgent, StateGraph, create_react_agent, ToolPolicy, Vector Store, Memory Buffer, and 1-Line HTTP/SSE Serving.

3. Fail-Closed Identity Verification & Capability Profiling

ServerIdentityVerifier automatically identifies local inference engines (termux-aichain, llama-server, BitNet.cpp, OpenAI).
When /health returns generic status, capability fallback queries /v1/models to ensure model identity matches before dispatching sensitive device actions.

4. Default-Deny Tool Authorization Policy

All tools execute under ToolPolicy(default="deny") with JSON Schema bounds validation and optional asynchronous user approval callbacks.

🐍 Python Quickstart

Installation (pip)

pip install --upgrade termux-aichain

10-Second Hello Agent

from termux_aichain import LocalAgent

# Connects to local llama-server or OpenAI-compatible backend
agent = LocalAgent.local(model="qwen2.5-1.5b")
response = agent.run("Hello! Introduce yourself in one concise sentence.")
print(response)

🟩 Node.js / TypeScript Quickstart

Installation (npm)

npm install termux-aichain

10-Second Hello Agent (ESM)

import { LocalAgent } from "termux-aichain";

// Connects to local llama-server or OpenAI-compatible backend
const agent = await LocalAgent.local("qwen2.5-1.5b");
const response = await agent.run("Hello! Introduce yourself in one concise sentence.");
console.log(response);

📱 Android Termux Setup

Option A: One-Touch Python Setup (Recommended)

pip install --upgrade termux-aichain
termux-aichain install

termux-aichain install automatically provisions all necessary Termux packages (termux-api, ffmpeg, git, nodejs-lts) in a single step with zero manual configuration.

Option B: 1-Line Bootstrap Script (Termux Bash)

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

📋 10 Copy-Paste Production Recipes

[Python] 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:\n{log}\n"
    "Respond in strict 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 (zero external dependencies)
chain = prompt | llm | parser

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

[Python] Recipe 2: Autonomous ReAct Multi-Agent with StateGraph & Hardware Actuation

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

# 1. Initialize local engine
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 Output:", state["messages"][-1].content)

[Python] Recipe 3: SQLite ACID Long-Term Memory & Pure Cosine Vector RAG

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})")

[Python] Recipe 4: 1-Line REST & SSE Streaming Agent Server

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 /invoke, POST /stream) and Web Dashboard UI on localhost
serve(agent, host="127.0.0.1", port=8000)

[Python] Recipe 5: Full Multimodal Ecosystem Pipeline (STT + Diffusion + Playwright)

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.")]
})
print("Multimodal Result:", state["messages"][-1].content)

[Node.js] Recipe 6: 1-Line LocalAgent Facade & Automatic Verification

import { LocalAgent } from "termux-aichain";

// Automatically verifies server capability, protocol, and model ID
const agent = await LocalAgent.local("qwen2.5-1.5b", {
  endpoint: "http://127.0.0.1:8080"
});

const result = await agent.run("Summarize key advantages of on-device AI in 3 bullet points.");
console.log(result);

[Node.js] Recipe 7: Cyclic StateGraph Machine & Conditional Branching

import { StateGraph, START, END } from "termux-aichain";

const workflow = new StateGraph();

workflow.addNode("step_a", async (state) => {
  console.log(`[Node A] Count: ${state.count}`);
  return { count: state.count + 1 };
});

workflow.setEntryPoint("step_a");
workflow.addConditionalEdges("step_a", (state) => (state.count >= 3 ? END : "step_a"));

const app = workflow.compile();
const finalState = await app.invoke({ count: 0 });
console.log("Graph Complete:", finalState);

[Node.js] Recipe 8: In-Memory MicroVectorStore Similarity Search

import { MicroVectorStore } from "termux-aichain";

const vectorStore = new MicroVectorStore();

vectorStore.addTexts(
  ["Linux Kernel Bionic Architecture", "ARM NEON SIMD Assembly", "WebGPU Compute Shaders"],
  [
    [0.95, 0.10, 0.05],
    [0.85, 0.40, 0.10],
    [0.05, 0.15, 0.98]
  ]
);

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

[Node.js] Recipe 9: 1-Line REST & SSE Streaming Server

import { serve, PromptTemplate } from "termux-aichain";

const prompt = PromptTemplate.fromTemplate("Echo and analyze: {msg}");

// Serves POST /invoke and POST /stream with loopback CORS protection
const server = serve(prompt, {
  host: "127.0.0.1",
  port: 8080,
  apiKey: "optional_secret_token"
});

[Node.js] Recipe 10: Android Native Hardware Actuation Tools

import {
  getBatteryStatus,
  getSensorData,
  getDeviceLocation,
  vibrateDevice,
  sendNotification
} from "termux-aichain";

// 1. Read battery percentage (CLI or kernel sysfs fallback)
const battery = await getBatteryStatus.func();
console.log("Battery Status:", battery);

// 2. Vibrate device for 300ms
await vibrateDevice.func({ duration_ms: 300 });

// 3. Dispatch Android Notification
await sendNotification.func({
  title: "AI Workstation",
  content: "Autonomous task execution completed successfully.",
  priority: "high"
});

🛠️ 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`)

📊 Empirical Benchmarks (Galaxy S20)

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

🔒 Audit & Verification Summary

Verification Scope: 153/153 automated tests passed with zero observed failures or errors in the verified test scope (136 Python tests, 17 Node.js tests).
TypeScript Zero-Drift: Full compilation parity between js/src/**/*.ts SSOT and js/esm/ release output.
Fail-Closed Security: ServerIdentityVerifier fail-closed backend validation, tool policy default="deny", loopback CORS, and constant-time token comparison.

📜 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).