Add Hugging Face Spaces deployment files

DEPLOY_TO_SPACES.md

@@ -0,0 +1,175 @@
+# 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.

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application
+COPY . .
+
+# Hugging Face Spaces uses port 7860
+ENV PORT=7860
+
+# Run the FastAPI server
+CMD ["bash", "-c", "uvicorn server:app --host 0.0.0.0 --port ${PORT}"]

create_space.py

@@ -0,0 +1,40 @@
+from huggingface_hub import HfApi, login
+import sys
+
+def create_space():
+    # Get token from user
+    token = input("Enter your Hugging Face access token (from https://huggingface.co/settings/tokens): ")
+    
+    # Login with token
+    login(token=token)
+    api = HfApi()
+    
+    # Get username
+    username = input("Enter your Hugging Face username: ")
+    space_name = "local-inference"
+    
+    space_id = f"{username}/{space_name}"
+    print(f"Creating Space: {space_id}")
+    
+    try:
+        api.create_repo(
+            repo_id=space_id,
+            repo_type="space",
+            space_sdk="docker",
+        )
+        print(f"\nSpace created successfully!")
+        print(f"Remote URL: https://huggingface.co/spaces/{space_id}")
+        print("\nNext steps:")
+        print("1. Initialize git in this directory (if not already done)")
+        print("2. Add the remote:")
+        print(f"   git remote add origin https://huggingface.co/spaces/{space_id}")
+        print("3. Push your code:")
+        print("   git add .")
+        print('   git commit -m "Initial commit"')
+        print("   git push -u origin main")
+    except Exception as e:
+        print(f"Error creating space: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    create_space()

verify_install.py

@@ -0,0 +1,15 @@
+import importlib
+
+packages = [
+    'fastapi',
+    'torch',
+    'transformers',
+]
+
+for p in packages:
+    try:
+        m = importlib.import_module(p)
+        v = getattr(m, '__version__', None)
+        print(f"{p}: OK, version={v}")
+    except Exception as e:
+        print(f"{p}: IMPORT ERROR: {e}")