Add FastAPI serving example

serving/.env.example

@@ -0,0 +1,22 @@
+# Copy to .env — signsdk auto-loads it.
+
+# Device: cuda (GPU) or cpu. Needs the signsdk[gpu] install for cuda.
+SIGNSDK_DEVICE=cuda
+
+# Models kept resident (LRU; evicting frees the GPU). Each SpaMo is ~11.5 GB on GPU,
+# so on a 24 GB card keep this at 1.
+SIGNSDK_MAX_RESIDENT=1
+
+# Fall back to CPU if fewer than this many MiB are free on the GPU (avoids OOM).
+# SIGNSDK_SPAMO_GPU_MIB=22000
+# SIGNSDK_UNISIGN_GPU_MIB=5000
+
+# Cap input frames for SpaMo (native max_frame_length=512). Lower if a long clip OOMs.
+# SIGNSDK_MAX_FRAMES=512
+
+# VideoMAE batch (lower = less GPU memory). Default 8.
+# SIGNSDK_MAE_BATCH=8
+
+# Where models are cached (default ~/.cache/signsdk) / which HF repo to pull from.
+# SIGNSDK_HOME=/data/signsdk
+# SIGNSDK_HF_REPO=croco-corp/pjm-models

serving/README.md

@@ -0,0 +1,35 @@
+# Serving the PJM models (FastAPI)
+
+A minimal FastAPI server over [`signsdk`](https://pypi.org/project/signsdk) — upload a
+sign-language video, get English text. Models are pulled from this HF repo on first use.
+
+## Run
+
+```bash
+uv venv
+uv pip install "signsdk[gpu]"          # GPU; or "signsdk[cpu]" / plain "signsdk"
+cp .env.example .env                   # optional: tune device + memory
+uv run uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+**GPU note:** `rtmlib` pins CPU `onnxruntime`, so add this to your `pyproject.toml` to keep
+the GPU wheel:
+```toml
+[tool.uv]
+override-dependencies = ["onnxruntime ; sys_platform == 'never'"]
+```
+
+## Use
+
+```bash
+# list models
+curl localhost:8000/models
+
+# translate (default model = unisign-pjm-how2sign-ms)
+curl -F video=@clip.mp4 -F model=spamo-pjm-phoenix-ms localhost:8000/translate
+```
+
+## Memory (`.env`)
+Each SpaMo model is ~11.5 GB on GPU (~21 GB peak). On a 24 GB card set
+`SIGNSDK_MAX_RESIDENT=1` — `signsdk.load()` then frees the resident model before loading a
+new one. If the GPU is too full, it falls back to CPU instead of OOMing. See `.env.example`.

serving/app.py

@@ -0,0 +1,67 @@
+"""FastAPI serving example for the PJM sign-language → English models (signsdk).
+
+Quick start:
+    uv venv && uv pip install "signsdk[gpu]"      # or signsdk[cpu] / plain signsdk
+    cp .env.example .env                          # tune device / memory
+    uv run uvicorn app:app --host 0.0.0.0 --port 8000
+
+Endpoints:
+    GET  /            health + default model
+    GET  /models      list the 16 models (filter ?backend=unisign|spamo)
+    POST /translate   upload a video, get the decoded text
+                      form fields: model, num_beams, max_new_tokens
+
+Memory: models are loaded via signsdk.load() — an LRU cache that frees the GPU when it
+evicts. Each SpaMo model is ~11.5 GB / ~21 GB peak, so on a 24 GB card keep
+SIGNSDK_MAX_RESIDENT=1 (see .env.example). If a model won't fit, signsdk falls back to CPU.
+"""
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+
+import signsdk
+from signsdk import GenerationConfig, SignTranslatorError
+
+app = FastAPI(title="PJM sign-language translation", version="1.0")
+
+
+@app.get("/")
+def health():
+    return {"status": "ok", "default_model": signsdk.DEFAULT_MODEL}
+
+
+@app.get("/models")
+def models(backend: Optional[str] = None):
+    """List available models. Filter with ?backend=unisign or ?backend=spamo."""
+    return {"default": signsdk.DEFAULT_MODEL, "models": signsdk.describe_models(backend)}
+
+
+@app.post("/translate")
+async def translate(
+    video: UploadFile = File(..., description="sign-language video clip (mp4)"),
+    model: str = Form(signsdk.DEFAULT_MODEL),
+    num_beams: int = Form(4),
+    max_new_tokens: int = Form(64),
+):
+    """Translate one uploaded sign-language video to text."""
+    suffix = Path(video.filename or "clip.mp4").suffix or ".mp4"
+    tmp = tempfile.NamedTemporaryFile(suffix=suffix, delete=False)
+    try:
+        shutil.copyfileobj(video.file, tmp)
+        tmp.close()
+        gen = GenerationConfig(num_beams=num_beams, max_new_tokens=max_new_tokens)
+        try:
+            result = signsdk.load(model).predict(tmp.name, generation=gen)
+        except SignTranslatorError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        return {
+            "text": result.text,
+            "model": result.model,
+            "lang": result.lang,
+            "timings": result.timings,
+        }
+    finally:
+        Path(tmp.name).unlink(missing_ok=True)