munyew/mina-bridge

MINA Bridge v4 — Sovereign Edge AI Gateway

MINA (My Intelligent National Assistant) is Singapore's sovereign edge AI companion, built on 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

{
  "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.

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

POST /completion

Main inference endpoint. Accepts two input modes:

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

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

Mode B — Raw WAV audio (whisper path):

{
  "prompt": [{
    "prompt_string": "...",
    "multimodal_data": ["<base64-WAV>"]
  }]
}

Response:

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

# 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
🟠 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 IMDA/NUS

---

Citation

@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    = {IMDA NMLP — ATxSG 2026}
}

---

Acknowledgements

Built on MERaLiON-2-3B by IMDA National Multimodal LLM Programme.
Speech transcription via whisper.cpp.
On-device inference via llama.cpp.