---
title: UCL AI VIM · SAM Assist
emoji: 🩺
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 5.9.1
python_version: "3.11"
app_file: app.py
pinned: false
hardware: cpu-basic
license: apache-2.0
short_description: SAM 2 + MedSAM 2 + Grounded-SAM 2 backend for UCL AI VIM
---

# UCL AI VIM · SAM Assist (HF Space — CPU Basic)

Free, no-credit-card backend for the [UCL AI VIM annotation app](https://syncsurge.netlify.app/).
Exposes three SAM-family models behind a Gradio app on **CPU Basic**
(2 vCPU, 16 GB RAM, no GPU).

| model           | use                          | text? |
| --------------- | ---------------------------- | ----- |
| `sam2`          | point prompts (general)      | no    |
| `medsam2`       | point prompts (medical)      | no    |
| `grounded_sam2` | text prompts via Grounding DINO + SAM 2 | yes |

## ⚠️ Honest expectations (CPU-only)

- **First call after a cold start: 60–120 s** while the chosen model downloads
  and loads into RAM. Subsequent calls reuse the cached weights.
- **Point prompt: ~10–30 s** per call once warm.
- **Text prompt: ~30–60 s** per call once warm (DINO + SAM2 in series).
- **Video tracking is NOT exposed here.** Per-call CPU time + HF's request
  timeout combine into something that never finishes. Tracking needs the
  local FastAPI backend (see `../sam/`).
- **Free CPU Spaces sleep after 48 hours** of no traffic. First call after
  sleep wakes the Space — add another 30–60 s on top of the warm timings above.

If you want interactive-speed inference, run the FastAPI backend locally
against your own GPU and expose it via Cloudflare Tunnel — see the top-level
project README for that path.

## API

Endpoints follow Gradio's predict contract. POST JSON:

```
POST https://<owner>-<space>.hf.space/run/segment_point
POST https://<owner>-<space>.hf.space/run/segment_text
POST https://<owner>-<space>.hf.space/run/healthz
POST https://<owner>-<space>.hf.space/run/classes
```

Body: `{"data": [positional, args, in, signature, order]}` — return value is
`{"data": ["<json-encoded-string>"]}`.

The React frontend at `client/src/features/review/SamBridge.jsx` handles all
of that automatically when `VITE_SAM_API_TYPE=gradio`.

## Deployment

1. **Create the Space** at https://huggingface.co/new-space
   - SDK: **Gradio** · Hardware: **CPU Basic** (free) · Public

2. **Push the three files** (web UI or CLI):
   ```bash
   cd /home/capla/Documents/ucl-ai-vim/server/sam_hfspace
   pip install huggingface_hub
   huggingface-cli login
   huggingface-cli upload <USER>/<SPACE-NAME> ./ . --repo-type=space
   ```

3. **Wait for first build** (~6–10 min — installs PyTorch + segment-anything-2).
   Watch the Space's **Logs** tab. When status flips to `Running`, the API is
   live at `https://<USER>-<SPACE-NAME>.hf.space`.

4. **Point the Netlify site at the Space.** In Netlify env:
   ```
   VITE_SAM_API_URL  = https://<USER>-<SPACE-NAME>.hf.space
   VITE_SAM_API_TYPE = gradio
   ```
   Re-build locally with those vars and re-drop `client/dist/`:
   ```bash
   cd /home/capla/Documents/ucl-ai-vim/client
   VITE_SAM_API_URL=https://<USER>-<SPACE-NAME>.hf.space \
   VITE_SAM_API_TYPE=gradio \
   npm run build
   ```
   then drag `dist/` to https://app.netlify.com/drop on top of your existing site.

## Local test (without HF)

```bash
pip install -r requirements.txt
python app.py
# Gradio dev server on http://127.0.0.1:7860
```