| --- |
| title: ToneBridge |
| emoji: 🏮 |
| colorFrom: red |
| colorTo: yellow |
| sdk: gradio |
| sdk_version: 6.18.0 |
| python_version: '3.10' |
| app_file: app.py |
| pinned: false |
| short_description: A gentle Mandarin sentence coach. |
| tags: |
| - build-small-hackathon |
| - backyard-ai |
| - thousand-token-wood |
| - openbmb |
| - minicpm |
| - openai-codex |
| - modal |
| - track:backyard |
| - track:wood |
| - sponsor:openbmb |
| - sponsor:openai |
| - sponsor:modal |
| - achievement:offgrid |
| - achievement:welltuned |
| - achievement:offbrand |
| - achievement:fieldnotes |
| |
| - off-brand |
| - off-the-grid |
| - well-tuned |
| - off-brand |
| - field-notes |
| - best-demo |
| - bonus-quest-champion |
| - judges-wildcard |
| models: |
| - Alphaplasti/ToneBridge-MiniCPM4.1-8B |
| --- |
| |
| # ToneBridge - Mandarin sentence coach |
|
|
| > Build natural Mandarin sentences, one small correction at a time. |
|
|
| Built for the Hugging Face **Build Small Hackathon**. |
|
|
| ## Contributer |
| - **@Alphaplasti** |
| - **@ZHAO JINGZI** |
|
|
|
|
| ## The Problem |
|
|
| Beginner Mandarin learners often know what they want to say, but not whether the sentence sounds natural, polite, or appropriate for the social context. |
|
|
| Classic translators tend to rewrite too much. Grammar tools often explain too much. A beginner needs something narrower: keep my meaning, fix only what is needed, show the pinyin, and tell me why in plain English. |
|
|
| **ToneBridge is built for that moment.** You choose one context-tone profile, write or speak one Chinese sentence, and get a small, practical correction designed for learning rather than translation. |
|
|
| ## What It Does |
|
|
| ToneBridge returns: |
|
|
| - one corrected Mandarin sentence; |
| - pinyin with tone marks under Chinese text; |
| - a short error type; |
| - a concise explanation in English; |
| - a practical tip for next time; |
| - a natural Mandarin reading voice with a follow-along reading view. |
|
|
| The correction prompt is intentionally conservative: if the sentence is already correct and natural, the corrected sentence should remain unchanged. |
|
|
| ## How It Works |
|
|
| 1. The learner selects one profile: **Friendly-informal**, **Work-informal**, **Work-formal**, **Wechat-informal**, or **Wechat-formal**. |
| 2. ToneBridge applies a conservative tone-aware correction for that profile. |
| 3. They type a Chinese sentence, or use browser speech recognition. |
| 4. MiniCPM corrects the sentence while preserving the learner's meaning and length. |
| 5. The frontend adds pinyin under Chinese text. |
| 6. Edge TTS generates a fast Mandarin Neural reading of the corrected sentence. |
| 7. The reading panel highlights characters while the audio plays. |
|
|
| ## What's Inside |
|
|
| | Component | Model / Library | Where it runs | |
| | --- | --- | --- | |
| | Sentence correction | **Alphaplasti/ToneBridge-MiniCPM4.1-8B** via `transformers` | ZeroGPU / GPU-backed Space | |
| | Mandarin reading voice | `edge-tts` with `zh-CN-YunjianNeural` by default | Server | |
| | Pinyin | `pypinyin` with tone marks | CPU | |
| | Voice input | Browser Web Speech API | Browser-dependent | |
| | Frontend | Custom HTML/CSS/JS served by `gr.Server` | Browser | |
| | Backend API | `gr.Server` + `@app.api()` endpoints | Hugging Face Space | |
|
|
| The active model pipeline stays under the 32B-parameter target: the main correction model is 8B, and the default reading voice uses a lightweight server-side Edge TTS call instead of loading a second GPU model. |
|
|
| ## Hardware And Loading |
|
|
| ToneBridge is designed for Hugging Face ZeroGPU. |
|
|
| - The correction model is preloaded at Space startup so it is not reloaded on every correction. |
| - The reading voice uses Edge TTS by default, so replay avoids loading a heavy server-side TTS model. |
|
|
| ## Space Variables |
|
|
| Useful environment variables: |
|
|
| ```text |
| MODEL_ID=Alphaplasti/ToneBridge-MiniCPM4.1-8B |
| TTS_PROVIDER=edge |
| ENABLE_SERVER_TTS=true |
| EDGE_TTS_VOICE=zh-CN-YunjianNeural |
| EDGE_TTS_RATE=+0% |
| EDGE_TTS_PITCH=+0Hz |
| EDGE_TTS_VOLUME=+0% |
| EDGE_TTS_KARAOKE_DURATION_FACTOR=0.86 |
| LOAD_IN_4BIT=true |
| PRELOAD_MODEL=true |
| MAX_INPUT_CHARS=1200 |
| MAX_NEW_TOKENS=220 |
| METRICS_FILE=tonebridge_usage_metrics.jsonl |
| METRICS_REPO_SYNC=false |
| METRICS_REPO_ID=build-small-hackathon/Tone-Bridge |
| METRICS_REPO_PATH=tonebridge_usage_metrics.jsonl |
| HF_METRICS_TOKEN=<write token as a Space secret> |
| ``` |
|
|
| If the correction model is private, add `HF_TOKEN` as a Space secret with read access to `Alphaplasti/ToneBridge-MiniCPM4.1-8B`. |
|
|
| ## Usage Metrics And Feedback |
|
|
| Every saved correction is written to `tonebridge_usage_metrics.jsonl` in the running Space app folder by default. Relative `METRICS_FILE` values are resolved from the folder that contains `app.py`. |
|
|
| The Hugging Face **Files** tab shows the Space git repository, not every runtime file created while the app is running. To make the metrics file appear in **Files**, enable repo sync: |
|
|
| ```text |
| METRICS_REPO_SYNC=true |
| METRICS_REPO_ID=build-small-hackathon/Tone-Bridge |
| METRICS_REPO_PATH=tonebridge_usage_metrics.jsonl |
| HF_METRICS_TOKEN=<write token as a Space secret> |
| ``` |
|
|
| If the Space is public, synced metrics are public too. Each record includes: |
|
|
| - `original_sentence` |
| - `corrected_sentence` |
| - `evaluation` (`thumbs_up`, `thumbs_down`, or `null`) |
| - `generation_time_seconds` |
| - status, context, tone, correction mode, error type, model id, timestamp, and request id |
|
|
| The app adds thumbs-up / thumbs-down buttons after each correction. Votes update the matching JSONL record automatically. |
|
|
| Use **Settings > Sync metrics file** to force a repository upload and see the exact sync error in the app. If the file still does not appear in the Hugging Face **Files** tab, check that `METRICS_REPO_ID` points to the Space repo and that `HF_METRICS_TOKEN` is a Space secret with write access. |
|
|
| ## Reachy Mini Integration |
|
|
| The Settings panel can send each correction to a local Reachy Mini endpoint from the learner's browser. This is browser-side on purpose: a Hugging Face Space server usually cannot reach a private LAN IP such as `192.168.x.x`. |
|
|
| Default endpoint: |
|
|
| ```text |
| http://<REACHY_IP>:80/api/tonebridge |
| ``` |
|
|
| Payload shape: |
|
|
| ```json |
| { |
| "source": "ToneBridge", |
| "event": "correction", |
| "status": "correct or corrected", |
| "emotion": "happy or thinking", |
| "speech": "encouragement or corrected Mandarin sentence", |
| "speech_language": "fr-FR or zh-CN", |
| "original_sentence": "...", |
| "corrected_sentence": "...", |
| "error_type": "...", |
| "generation_time_seconds": 3.2 |
| } |
| ``` |
|
|
| If the sentence is already correct, Reachy receives `emotion: "happy"` and a short encouraging French sentence. If ToneBridge made a correction, Reachy receives `emotion: "thinking"` and the corrected Mandarin sentence as the speech text. |
|
|
| Your local Reachy endpoint or bridge must allow browser POST requests from the Space origin. If the browser blocks the request, add CORS support on the local bridge or expose an HTTPS local endpoint. |
|
|
| MiniCPM4.1 currently expects a Transformers 4.x runtime. `requirements.txt` pins `transformers>=4.56.0,<5.0.0` because Transformers 5 removed an internal helper still imported by the model's remote code. |
|
|
| ## Repository |
|
|
| ```text |
| . |
| ├── app.py # gr.Server app, API endpoints, frontend, correction and TTS logic |
| ├── requirements.txt # Python dependencies |
| └── README.md |
| ``` |
|
|
| ## Credits |
|
|
| - **OpenBMB** - MiniCPM4.1-8B base model. |
| - **Hugging Face Spaces** - hosting, ZeroGPU, and the Build Small Hackathon. |
| - **Gradio** - `gr.Server`, queue/API infrastructure, and client compatibility. |
|
|
| ## All Relevant Links |
|
|
| - Live Space: [ToneBridge on Hugging Face Spaces](https://huggingface.co/spaces/build-small-hackathon/Tone-Bridge) |
| - Fine-tuned model: [Alphaplasti/ToneBridge-MiniCPM4.1-8B](https://huggingface.co/Alphaplasti/ToneBridge-MiniCPM4.1-8B) |
| - Dataset: [Alphaplasti/tonebridge-metrics](https://huggingface.co/datasets/Alphaplasti/tonebridge-metrics) |
| - Community Blog: [ToneBridge: Fine-Tuning a Small Mandarin Coach for Context-Aware Corrections] (https://huggingface.co/blog/build-small-hackathon/tonebridge-fine-tuning-a-small-mandarin-coach-for) |
| - |
| |
| ## All Relevant Links |
| - Demo video: [ToneBridge Demo on YouTube](https://www.youtube.com/watch?v=ivgE5TJY7Mc) |
| - X / Twitter post: [ToneBridge announcement on X](https://x.com/jingzi_zhao_x/status/2066131768302850161) |
| - LinkedIn: https://www.linkedin.com/posts/jingzizhao_tonebridge-a-hugging-face-space-by-build-small-hackathon-share-7471909868619206656-rpF2/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAEhuC3wBuxIz2RG3eXfMGjg0-IcyvdK-wsk |
| - Hackathon Diary #1: [Build Small Hackathon Diary #1](https://www.youtube.com/watch?v=zAikxiVqwmg&t=13s) |
| - Hackathon Diary #2: [Build Small Hackathon Diary #2](https://www.youtube.com/watch?v=4waOzX48tUk&t=4s) |
| --- |
|
|
| *ToneBridge - gentle Mandarin correction for real learners.* |
