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