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:

```powershell
$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:

```text
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:

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

## 3. Upload The Space

From the repo root:

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

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

```powershell
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:

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