README.md

# SAM2.1 Highlight Mask Endpoint

Custom Hugging Face Inference Endpoint handler for Agatha collection highlights.

The endpoint wraps `facebook/sam2.1-hiera-base-plus` with Meta's official
`sam2.sam2_image_predictor.SAM2ImagePredictor` API and exposes the exact contract
the backend expects:

```json
{
  "inputs": {
    "image_base64": "...",
    "mime_type": "image/png",
    "boxes": [
      { "id": "sofa", "box": { "x1": 120, "y1": 300, "x2": 640, "y2": 760 } }
    ]
  }
}
```

Response:

```json
{
  "masks": [
    {
      "id": "sofa",
      "score": 0.93,
      "mask_png_base64": "...",
      "box": { "x1": 120, "y1": 300, "x2": 640, "y2": 760 },
      "mime_type": "image/png"
    }
  ]
}
```

`requirements.txt` intentionally avoids `transformers`. The model card supports
a Transformers route, but the stable first-party path for this custom endpoint is
`SAM2ImagePredictor.from_pretrained("facebook/sam2.1-hiera-base-plus")`. The
handler calls `set_image()` once per request and segments all provided boxes in
one predictor call.

Upload `handler.py` and `requirements.txt` to a Hugging Face model repo, then
deploy that repo as an Inference Endpoint with task `Custom`.