File size: 6,804 Bytes

264f56c

---

language:
- en
- zh
- ms
- ta
license: apache-2.0
tags:
- singapore
- sovereign-ai
- edge-ai
- meralion
- singlish
- agentic-innovation
- android
- flask
- whisper
- on-device
pipeline_tag: text-generation
library_name: custom
---


# MINA Bridge v4 — Sovereign Edge AI Gateway

**MINA** (My Intelligent National Assistant) is Singapore's sovereign edge AI companion, built on [MERaLiON-2-3B](https://huggingface.co/MERaLiON/MERaLiON-2-3B) by IMDA.

`mina-bridge` is the intelligence gateway between the MINA Android APK and the on-device MERaLiON model — a lightweight Flask server that handles speech transcription, rule-based agent routing, response generation, and autonomous gap logging, all running locally on a Termux environment with no cloud dependency for inference.

---

## Architecture

```

Android APK

    │  base64 WAV / pre-transcribed text

    ▼

mina-bridge  (Flask :8081)

    ├── whisper-cli  ← speech-to-text (offline)

    ├── route_agent()  ← rule-based ARIA routing (no LLM call)

    ├── build_prompt()  ← agent-specific focused prompt

    ├── llama-server :8080  ← MERaLiON-2-3B GGUF inference

    ├── append_resources()  ← hotlines from mina_knowledge.json

    └── log_gap() + ntfy  ← autonomous cloud sync

```

**Option 3 architecture**: routing is pure Python — deterministic, zero-latency, zero hallucination risk. The LLM is called exactly once per turn, only to generate the response text.

---

## Features

### 🎙️ Whisper.cpp STT Integration
Offline speech-to-text via `whisper-cli` subprocess. Accepts base64-encoded WAV from the Android APK, decodes to a temp file, runs `ggml-base.bin`, strips noise tokens (`[BLANK_AUDIO]`, `debugfs`, `MEMPROF`), and returns clean transcript text. No cloud STT dependency.

### 🧭 ARIA Agent Routing
Four specialist agents dispatched by keyword matching — no LLM routing call:

| Agent | Trigger keywords | Purpose |
|---|---|---|
| **VITA** | `giving up`, `want to die`, `hopeless`, `hurt myself` … | Crisis support |
| **SENTINEL** | `scam`, `bank account`, `transfer money`, `spf` … | Scam detection |
| **KRONOS** | `meeting`, `calendar`, `schedule`, `tomorrow` … | Calendar assistance |
| **MINA** | *(default)* | Stress / general emotional support |

### 🧠 Knowledge Base Integration
Reads `mina_knowledge.json` at runtime for:
- Crisis hotline numbers (SOS Lifeline, IMH) — phone + WhatsApp links
- Capability flags (`make_phone_call`, `send_whatsapp`, `check_calendar`, …)

Resources appended to VITA and SENTINEL replies are driven by the knowledge file, not hardcoded strings. Update the JSON to update the response — no code change needed.

### 📋 Gap Logging & Autonomous Learning
Every time a user requests a capability MINA doesn't yet have, `log_gap()`:
1. Appends a structured entry to `gaps/gap_log.jsonl` (local, persistent)
2. POSTs to `ntfy.sh/{NTFY_TOPIC}` for real-time cloud sync

```json

{

  "timestamp": "2026-05-02T14:23:01",

  "gap_type": "make_phone_call",

  "user_request": "can you call SOS for me",

  "context": "User requested phone call to SOS",

  "status": "pending"

}

```

The `NTFY_TOPIC` env var controls the notification channel (default: `roar-imda-demo`). Gap notifications appear in the ntfy app with tag `brain` for triage. Network failures are caught silently — gap is always written locally first.

### 🔒 Sovereign & Offline-First
All inference runs on-device. The only outbound network call is the optional ntfy gap sync (non-blocking, non-critical path). No user speech or transcript data leaves the device during inference.

---

## Endpoints

### `GET /health`
Liveness probe. Android APK polls this at startup every 3 s.
```json

{"status": "ok", "llama": true, "bridge": "v2"}

```

### `POST /completion`
Main inference endpoint. Accepts two input modes:

**Mode A — Pre-transcribed text** (fast path):
```json

{"transcript": "I have a meeting tomorrow morning"}

```

**Mode B — Raw WAV audio** (whisper path):
```json

{

  "prompt": [{

    "prompt_string": "...",

    "multimodal_data": ["<base64-WAV>"]

  }]

}

```

**Response**:
```json

{

  "reply":      "Sure lah, let me check your calendar!",

  "content":    "Sure lah, let me check your calendar!",

  "transcript": "I have a meeting tomorrow morning",

  "emotion":    "neutral",

  "valence":    0.50,

  "arousal":    0.38,

  "dominance":  0.50,

  "agent":      "KRONOS",

  "risk":       "none",

  "elapsed":    1.84

}

```

---

## Configuration

| Env var | Default | Description |
|---|---|---|
| `LLAMA_URL` | `http://localhost:8080` | llama-server endpoint |
| `BRIDGE_PORT` | `8081` | Flask listen port |
| `MAX_TOKENS` | `256` | Max tokens for transcription call |
| `NTFY_TOPIC` | `roar-imda-demo` | ntfy.sh topic for gap sync |

---

## Deployment (Termux)

```bash

# Prerequisites on device

pkg install python whisper-cpp llama-cpp



# Clone and deploy

git clone https://huggingface.co/munyew/mina-bridge

cd mina-bridge



# Start bridge (watchdog via start_mina.sh)

nohup python3 bridge.py >> bridge.log 2>&1 &



# Or restart after update

pkill -f bridge.py && sleep 3 && nohup python3 bridge.py >> bridge.log 2>&1 &

```

Expected paths on Termux:
```

~/whisper.cpp/build/bin/whisper-cli

~/whisper.cpp/models/ggml-base.bin

~/meralion/meralion-3b-decoder-q8_0.gguf

~/meralion/mina_knowledge.json

~/meralion/gaps/gap_log.jsonl          ← auto-created

```

---

## Roadmap

| Priority | Gap | Solution |
|---|---|---|
| 🔴 Critical | Emotion detection upgrade | Replace VAD lookup table with [MERaLiON-SER-v1](https://huggingface.co/MERaLiON/MERaLiON-SER-v1) |
| 🟠 High | Singlish Mental Health ASR | Fine-tune MERaLiON-2-3B on v5 dataset (3240 audio files) |
| 🟠 High | Singapore Legal Domain ASR | Generate + fine-tune on CPF/HDB/PDPA domain |
| 🟡 Medium | Edge-optimised SER | Quantize MERaLiON-SER-v1 to INT8/TFLite < 200 MB |
| 🟡 Medium | Code-switched Singlish-Mandarin | Pending MNSC dataset from NUS |

---

## Citation

```bibtex

@software{mina_bridge_2026,

  title   = {MINA Bridge: Sovereign Edge AI Gateway for Singapore},

  author  = {Loh, Mun Yew (Darren)},

  year    = {2026},

  url     = {https://huggingface.co/munyew/mina-bridge},

  note    = {Singapore AI Research — ATxSG 2026}

}

```

---

## Acknowledgements

Built on [MERaLiON-2-3B](https://huggingface.co/MERaLiON/MERaLiON-2-3B) by IMDA National Multimodal LLM Programme.  
Speech transcription via [whisper.cpp](https://github.com/ggerganov/whisper.cpp).  
On-device inference via [llama.cpp](https://github.com/ggerganov/llama.cpp).