README.md

metadata

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.