# localllm — Android Mobile Client & Network Agent Plan

**Location**: `~/dev/localllm/android/README.md`  
**Parent Project**: [localllm](file:///home/za/dev/localllm/DESIGN.md)  
**Base Prototype**: [basicsMar23](file:///home/za/dev/AndroidStudioProjects/basicsMar23/)  
**Status**: Active Plan & Architecture Specification (2026-08-03)

---

## 1. Executive Summary

This folder contains the roadmap, architecture, and code for porting
**`localllm`** to Android devices (e.g., Samsung Galaxy). The goal is to
evolve `localllm` from a desktop Python CLI into a mobile **Voice +
Multimodal AI Assistant** connected to a **Network Agent (SOS Channel)**
that accesses public web content.

```text
Android Phone (Samsung) - Kotlin App (basicsMar23)
  ├── Tab 1: KB Viewer (Android WebView rendering site/index.html)
  ├── Tab 2: Voice AI (STT Mic -> Local/Remote LLM -> TTS Speaker)
  └── Tab 3: Multimodal Agent (CameraX / Photo Picker -> Vision)
                         │
                         ▼ (HTTP REST / MCP / Tailscale)
Network Agent (SOS Channel) & Agent-Reach
  ├── Public Web Access: Twitter/X, Reddit, YouTube, GitHub, Bilibili
  ├── Pipeline: Web Search (ddgs) -> Crawler (crawl.py) -> Markdown
  └── Target Storage: aispace/search/ (AI Write Zone)
```

---

## 2. Phased Implementation Roadmap

### Phase 1: Kotlin WebView APK (Smallest Resistance Path)
* **Goal**: Get a working APK installed on Samsung phone to recall
  Android Studio skills.
* **Source Base**: Reuses [basicsMar23](file:///home/za/dev/AndroidStudioProjects/basicsMar23/)
  (Jetpack Compose `NavigationSuiteScaffold`, `MyTools`, `LlmManager`).
* **Tasks**:
  1. Compile static site on desktop:
     `PYTHONPATH=src uv run python -m py.stage && uv run mkdocs build`.
  2. Copy `site/` ➔ `app/src/main/assets/site/`.
  3. Add `KB` destination tab in `MainActivity.kt` with Compose
     `AndroidView(WebView)`.
  4. Load `file:///android_asset/site/index.html`.

### Phase 2: Voice Chat Integration (STT & TTS)
* **Goal**: Hands-free voice interaction with local/remote LLMs.
* **Tasks**:
  1. **Speech-to-Text (STT)**: Integrate Android `SpeechRecognizer`
     (`RecognizerIntent.ACTION_RECOGNIZE_SPEECH`) into chat bar.
  2. **Text-to-Speech (TTS)**: Integrate Android `TextToSpeech`
     (`android.speech.tts.TextToSpeech`) for spoken responses.

### Phase 3: Multimodal Vision & Photo Agent
* **Goal**: Let AI agents analyze images, code screenshots, and camera
  streams.
* **Tasks**:
  1. Add `PickVisualMedia()` photo picker and CameraX preview to app.
  2. Encode images to base64 and forward to vision-capable models
     (e.g., Gemini 2.5 Flash, Ollama `qwen2.5-vl` / `gemma-3`).

### Phase 4: Network Agent & Public Web Access (`Agent-Reach`)
* **Goal**: Allow mobile voice agents to search, crawl, and summarize
  public internet platforms into the Knowledge Base (`aispace/search/`).

---

## 3. Deep-Dive: Network Agent & `Agent-Reach` Integration

To give our Network Agent (SOS Channel) the ability to access public
web content without API fees, we integrate patterns from
[Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach).

### What is `Agent-Reach`?
`Agent-Reach` is an open-source tool exposing a unified CLI and **MCP
(Model Context Protocol) Server** for AI Agents to search and extract
content across 13+ public platforms without API keys:
* **Platforms Supported**: Twitter/X, Reddit, YouTube (video transcripts
  via `yt-dlp`), GitHub, Bilibili, Xiaohongshu, WeChat, Douyin, etc.
* **Zero API Cost**: Uses lightweight public scrapers and search endpoints.
* **Self-Healing**: Features `agent-reach doctor` to check connectivity
  and repair dependencies.

### How `localllm` Uses `Agent-Reach` for the Network Agent

1. **MCP / CLI Subcommand Integration**:
   * Integrate `Agent-Reach` as an MCP Server alongside `src/py/search.py`
     and `src/py/crawl.py`.
   * When an agent needs multi-platform information, it issues natural
     language reach commands (e.g., `agent-reach search "Xray ubuntu"`
     or `agent-reach youtube "https://youtu.be/..."`).

2. **Mobile Voice Query Workflow**:
   ```text
   User speaks to Samsung Phone: "Find recent Reddit posts on Xray"
                                     │
                                     ▼
                      Kotlin App Voice STT -> Agent Loop
                                     │
                                     ▼
                Calls Network Agent (src/py/search.py + Agent-Reach)
                                     │
                                     ▼
   Fetches Reddit/Web content -> Cleans HTML -> Writes aispace/search/
                                     │
                                     ▼
               LLM Summarizes -> Speaks response back via TTS
   ```

3. **Policy Safety Guarantee**:
   * Extracted web data from `Agent-Reach` is written strictly to
     `aispace/search/` (AI Write Zone).
   * Personal notes under `userdocs/` remain untouched and read-only.

---

## 4. Immediate Next Steps

1. Create initial Android Kotlin project structure under `android/`
   (or link with `basicsMar23`).
2. Implement asset copier script to transfer desktop `site/` build into
   Android `assets/site/`.
3. Build and test WebView APK on Samsung phone via USB / ADB.





<!-- zatranslate
target = ~/dev/localllm/aispace/translate/android.ui.design.md
from = en
to = cn
max_words = 388
-->