DEPLOY_TO_SPACES.md

# Deploying this project to Hugging Face Spaces

This document explains three ways to deploy the contents of this repository to a Hugging Face Space:

- Option A — Static Space (recommended for a plain website: fastest to set up)
- Option B — Gradio Space (if you want a Python-backed UI wired into models)
- Option C — Docker / "Other" Space (if you need to run `server.py` with FastAPI / Uvicorn)

All commands below assume PowerShell on Windows (your environment). If you use the workspace virtualenv, run the CLI commands from that environment or prepend the correct python -m calls.

## Preparation

1. Create a Hugging Face account if you do not already have one: https://huggingface.co/
2. Install Hugging Face Hub CLI locally (recommended inside your venv):

```powershell
&pip install --upgrade huggingface_hub
# then login interactively
& huggingface-cli login
```

3. Choose a Space name (e.g. `your-username/my-space`).

Note: Hugging Face Spaces supports several Space types. Pick the one that fits your app:

- `static` — best for a static website (HTML/CSS/JS). No Python runtime needed.
- `gradio` or `streamlit` — for Python UIs using those frameworks.
- `docker` or `other` — you provide a Dockerfile (useful for FastAPI or custom servers).

---

## Option A — Static Space (recommended for `index.html`/frontend-only sites)

Use this option when your site is pure client-side HTML/CSS/JS. It is the simplest and fastest option.

1. Ensure the static site entrypoint is `index.html` at the repository root. Currently this repo contains `static/index.html`. You can either:

   - Move content from `static/` to the repository root, or
   - Create a tiny wrapper `index.html` at repo root that loads `./static/index.html` with an iframe or server-side redirect (but moving is simplest).

   Example to copy files (PowerShell):

```powershell
# from repo root
Copy-Item -Path .\static\* -Destination . -Recurse -Force
```

2. Create the Space (replace `<your-username>` and `<space-name>`):

```powershell
huggingface-cli repo create <your-username>/<space-name> --type=static
```

3. Initialize a git repo and push the site to the new Space remote:

```powershell
git init
git add .
git commit -m "Deploy static site to HF Space"
# add remote; replace with the exact URL from the CLI output if different
git remote add origin https://huggingface.co/spaces/<your-username>/<space-name>
git branch -M main
git push -u origin main
```

4. Your Space will build and serve the static site. Visit https://huggingface.co/spaces/<your-username>/<space-name>

Notes:

- If you have large assets (models, weights), store them in a separate repo or use Git LFS. Spaces have storage limits.
- Static Spaces do not provide a Python runtime.

---

## Option B — Gradio Space (if you want a Python UI)

If you want to serve a simple Python UI that can interact with your models, use Gradio. This is great when you need Python code to run on the server side.

1. Create the Space as a Gradio type:

```powershell
huggingface-cli repo create <your-username>/<space-name> --type=gradio
```

2. Add a minimal `app.py` (Gradio) in the repo root. Example that serves your existing `static/index.html` inside a Gradio interface:

```python
import gradio as gr
from pathlib import Path

html = Path("static/index.html").read_text(encoding="utf-8")

def show():
    return html

iface = gr.Interface(fn=show, inputs=[], outputs=gr.HTML(), allow_flagging=False)

if __name__ == "__main__":
    iface.launch(server_name="0.0.0.0", server_port=7860)
```

3. Ensure `requirements.txt` includes `gradio` (add `gradio>=3.0` if missing). Commit and push like in Option A.

4. Visit your Space URL after the build completes.

Notes:

- Gradio Spaces run in a Python environment and will install packages from `requirements.txt`.
- Models and large files may require Git LFS or external hosting.

---

## Option C — Docker / "Other" Space (for FastAPI / custom servers)

Use this when you need to run `server.py` (FastAPI + Uvicorn) as the backend. This option gives you complete control via a Dockerfile.

1. Create the Space as a Docker/Other Space:

```powershell
huggingface-cli repo create <your-username>/<space-name> --type=docker
```

2. Add a `Dockerfile` to the repo root. Example for running `server.py` with Uvicorn:

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install --upgrade pip && pip install -r requirements.txt
ENV PORT=7860
CMD ["bash", "-lc", "uvicorn server:app --host 0.0.0.0 --port $PORT"]
```

Make sure `server.py` exposes a FastAPI `app` object (for example `app = FastAPI()`), so `uvicorn server:app` works.

3. Commit and push the repo to the Space remote as in Option A. Spaces will build the Docker image and run it.

Notes:

- Docker images must fit within Spaces resource constraints. Avoid bundling large model weights in the image; prefer downloading at runtime or using external storage.
- Use `$PORT` env var as shown so the platform can route correctly.

---

## Common tips

- If your `index.html` and assets live under `static/`, one simple approach is to move them to the repository root before pushing a Static Space.
- For debugging, check the Space build logs on the Space page — they show package install errors and startup logs.
- To upload large model files, use Git LFS or host the weights on the Hugging Face Hub (or external storage) and download them at runtime.

## Example minimal PowerShell session (Static Space)

```powershell
# login
huggingface-cli login
# create space
huggingface-cli repo create my-username/my-static-site --type=static
# copy files to repo root (if required)
Copy-Item -Path .\static\* -Destination . -Recurse -Force
# push
git init
git add .
git commit -m "Deploy static site to HF Space"
git remote add origin https://huggingface.co/spaces/my-username/my-static-site
git branch -M main
git push -u origin main
```

## Follow-ups I can help with

- Create a `Dockerfile` in this repo to run `server.py` on Spaces (I can add it and test locally).
- Add a `Gradio` `app.py` wrapper so the current `static/index.html` is served inside a Gradio app.
- Move/copy `static/` contents to the project root and configure a Static Space, then push for you (if you want me to modify repo files).

If you'd like, tell me which option you prefer (Static, Gradio, or Docker), and I will add the required files and example configuration in this repository.