# Rekognition shim (Python)

> A drop-in client that lets boto3 Rekognition code run against SightRadar with a two-line change, translating method names, arguments, scores and response shapes.

Source: https://sightradar.com/docs/sdks/rekognition-shim

```bash
pip install sightradar-rekognition-shim
```

The shim mirrors Rekognition's method names and argument shapes and translates responses back into Rekognition-shaped dictionaries (`FaceRecords`, `FaceMatches`, `Similarity`, `BoundingBox`). Zero dependencies, pure standard library. It is Python only; other AWS SDKs have no shim.

## The two-line change

_Before (boto3)_
```python
import boto3

rek = boto3.client("rekognition", region_name="us-east-1")

rek.create_collection(CollectionId="event-2026")
rek.index_faces(
    CollectionId="event-2026",
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "guest.jpg"}},
    ExternalImageId="guest-1",
)
res = rek.search_faces_by_image(
    CollectionId="event-2026",
    Image={"Bytes": open("selfie.jpg", "rb").read()},
    FaceMatchThreshold=90,
    MaxFaces=5,
)
for m in res["FaceMatches"]:
    print(m["Face"]["ExternalImageId"], m["Similarity"])
```

_After (shim)_
```python
from sightradar_rekognition_shim import client          # 1. swap the import

rek = client(api_key="frs_...")                          # 2. swap the constructor

rek.create_collection(CollectionId="event-2026")
rek.index_faces(
    CollectionId="event-2026",
    Image={"URL": "https://cdn.example.com/guest.jpg"},   # URL/GcsKey or Bytes
    ExternalImageId="guest-1",
)
res = rek.search_faces_by_image(
    CollectionId="event-2026",
    Image={"Bytes": open("selfie.jpg", "rb").read()},
    FaceMatchThreshold=90,
    MaxFaces=5,
)
for m in res["FaceMatches"]:
    print(m["Face"]["ExternalImageId"], m["Similarity"])
```

The rest of your call sites stay the same. `client()` with no arguments reads `SIGHTRADAR_API_KEY`.

## Mapped operations

| Rekognition method      | SightRadar endpoint                      |
| ----------------------- | ---------------------------------------- |
| `create_collection`     | `POST /v1/collections`                   |
| `delete_collection`     | `DELETE /v1/collections/{id}`            |
| `list_collections`      | `GET /v1/collections`                    |
| `describe_collection`   | `GET /v1/collections/{id}`               |
| `index_faces`           | `POST /v1/collections/{id}/index`        |
| `search_faces_by_image` | `POST /v1/collections/{id}/search`       |
| `search_faces` (by id)  | `POST /v1/collections/{id}/search-by-id` |
| `detect_faces`          | `POST /v1/detect`                        |
| `compare_faces`         | `POST /v1/compare`                       |

## Honest differences

* **Score scale.** Rekognition uses 0 to 100; SightRadar uses cosine similarity 0 to 1. The shim converts both ways: `FaceMatchThreshold=90` becomes `0.9`, and a returned `Similarity` is scaled back to 0 to 100. The scale converts; the right operating point does not. Read [choosing a threshold](/docs/guides/thresholds).
* **Bounding boxes.** Rekognition returns ratio boxes; SightRadar returns absolute pixels. The shim surfaces the pixel box under `SightRadarBBox` and computes the ratio `BoundingBox` only when you pass image dimensions via `_ImageSize=(w, h)`.
* **Image input.** `Image={"Bytes": ...}` is uploaded as multipart. The shim also accepts `{"URL": ...}` and `{"GcsKey": ...}`, and maps `{"S3Object": {"Bucket", "Name"}}` to a public `https://<bucket>.s3.amazonaws.com/<name>` URL, which must be fetchable.
* **`compare_faces`** accepts URL and GcsKey images, not raw `Bytes`, matching the `/v1/compare` contract.
* **Unsupported operations** (`detect_labels`, `detect_text`, `recognize_celebrities`, video, user vectors, per-face delete) raise `NotImplementedError` naming the limitation. They never silently no-op.
* **Nothing is lost.** Every response includes a `SightRadarRaw` key with the untranslated payload.

## Errors

All transport and API failures raise `SightRadarShimError` with `.message` and `.status_code`.

## Next

The [migration guide](/docs/guides/migrate-from-rekognition) covers re-indexing, dual-writing and cut-over.