| --- |
| title: HAL Voice MVP |
| emoji: 🔴 |
| colorFrom: red |
| colorTo: gray |
| sdk: docker |
| app_port: 7860 |
| pinned: false |
| short_description: Push-to-talk conversation with HAL 9000's voice. |
| --- |
| |
| # HAL Voice MVP |
|
|
| Push-to-talk web app that lets you talk to HAL 9000. FastAPI backend wires Groq Whisper (STT) → Claude (LLM) → Piper TTS (HAL voice). Sessions persist to disk as JSON. |
|
|
| ## Local setup |
|
|
| 1. Install espeak-ng (macOS): |
| ``` |
| brew install espeak-ng |
| ``` |
| 2. Create a virtual env and install deps: |
| ``` |
| python3 -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
| 3. Download the HAL Piper voice: |
| ``` |
| python download_model.py |
| ``` |
| 4. Create `.env`: |
| ``` |
| GROQ_API_KEY=gsk_... |
| ANTHROPIC_API_KEY=sk-ant-... |
| ``` |
| 5. (Optional) Edit `profile.md` with facts you want HAL to know about you. |
|
|
| ## Run locally |
|
|
| ``` |
| .venv/bin/uvicorn main:app --reload --port 8000 |
| ``` |
|
|
| Open http://localhost:8000, hold the red eye to talk, release to send. |
|
|
| ## Deploy to Hugging Face Spaces |
|
|
| 1. Create a new Space: https://huggingface.co/new-space |
| - SDK: **Docker** |
| - Hardware: **CPU Basic** (free) |
| - Visibility: Public (free) or Private ($9/mo) |
| 2. Add repository secrets (Settings → Variables and secrets): |
| - `GROQ_API_KEY` |
| - `ANTHROPIC_API_KEY` |
| 3. Push this repo to the Space: |
| ``` |
| git remote add space https://huggingface.co/spaces/<your-username>/<space-name> |
| git push space main |
| ``` |
| 4. The Space builds from the `Dockerfile`. First build takes ~5 min (downloads the HAL model). Subsequent builds are cached. |
| 5. Open the Space URL, hold the eye, talk. |
|
|
| ## Notes |
|
|
| - English only. The Piper HAL model is English-only by design. |
| - Sessions live in `data/sessions/` as JSON. On HF Spaces free tier, the filesystem is ephemeral — sessions reset on restart/rebuild. For persistence across restarts, upgrade to a Space with persistent storage ($5/mo) and set `HAL_DATA_DIR=/data`. |
| - Piper outputs 22050 Hz mono WAV, which browsers play natively. |
| - The HAL voice loads once at startup. |
| - Edit `profile.md` to give HAL static context about you; it gets prepended to the system prompt on startup. |
|
|
