docs/huggingface_space_deployment.md

Hugging Face Space Deployment Checklist

Use this checklist for the Build Small Hackathon Space under build-small-hackathon.

1. Deploy Modal Endpoints

modal serve is useful for local testing, but the hackathon Space needs stable endpoints. Deploy the runtime instead:

$env:MODAL_PROFILE="manikandanj"
$env:PYTHONUTF8="1"
$env:PYTHONIOENCODING="utf-8"
$env:TTY_COMPATIBLE="0"
.\.venv\Scripts\modal.exe deploy scripts\modal_audio.py

After deployment, copy the printed endpoint URLs for:

• time-machine-nemotron-stt
• time-machine-chatterbox-turbo-tts

2. Configure Space Secrets And Variables

Set these in the Hugging Face Space settings, or export them locally and run the helper below:

GRADIO_ROOT_PATH=https://build-small-hackathon-ai-time-machine.hf.space
TIME_MACHINE_ADAPTER_PROFILE=modal
TIME_MACHINE_LLM_API_KEY=<Together/OpenAI-compatible API key>
TOGETHER_API_KEY=<optional Together fallback key>
TIME_MACHINE_IMAGE_API_KEY=<optional image API key>
TIME_MACHINE_MODAL_STT_URL=<Modal Nemotron STT endpoint>
TIME_MACHINE_MODAL_TTS_URL=<Modal Chatterbox TTS endpoint>
TIME_MACHINE_MODAL_BEARER_TOKEN=<optional Modal endpoint bearer token>
TIME_MACHINE_MODAL_TTS_MODEL_FAMILY=chatterbox_turbo
TIME_MACHINE_MODAL_TTS_LATENCY_PROFILE=turbo

Keep secrets out of README.md, .env, and commits.

After hf auth login, this helper reads the current shell plus optional local .env / data/local.env files and sends API keys as Space secrets:

.\.runtime-venv\Scripts\python.exe scripts\configure_hf_space.py

3. Upload The Space

From the repo root:

powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hf_space.ps1

To upload and configure runtime variables/secrets in one pass:

powershell -ExecutionPolicy Bypass -File .\scripts\deploy_hf_space.ps1 -ConfigureRuntime

The .hfignore file excludes local virtualenvs, .env, traces, logs, and generated validator files.

4. Final README Links

Before judging, replace the placeholders in README.md:

• Demo video
• Social post

Then validate the public README at:

https://build-small-hackathon-field-guide.hf.space/submit