Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,207 @@
+---
+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 IMDA/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    = {IMDA NMLP — 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).