sightradar-rekognition-shim

A drop-in shim that lets code written against AWS Rekognition (via boto3) run against SightRadar with a ~2-line change.

SightRadar is a Rekognition-compatible face-recognition API. This package proves "drop-in": the client mirrors Rekognition's method names and argument shapes, and translates responses back into Rekognition-shaped dicts (FaceRecords, FaceMatches, Similarity, BoundingBox, …). Zero dependencies — pure stdlib.

Install

pip install sightradar-rekognition-shim

The 2-line change

Before — AWS Rekognition:

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 — SightRadar (only the client line changes):

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.

The API key can also come from the SIGHTRADAR_API_KEY environment variable, so client() with no arguments works too.

Mapped operations

Behavioural notes (honest differences)

• Score scale. Rekognition uses 0..100; SightRadar uses cosine similarity 0..1. The shim converts both ways automatically: your FaceMatchThreshold=90 becomes 0.9, and a returned Similarity is scaled back to 0..100.
• Bounding boxes. Rekognition returns ratio boxes (Left/Top/Width/Height, 0..1); SightRadar returns absolute pixel boxes. The shim surfaces the raw pixel box under SightRadarBBox, and only computes the ratio BoundingBox when you pass image dimensions via the private _ImageSize=(w, h) kwarg.
• Image input. Image={"Bytes": ...} is uploaded as multipart. The shim also accepts the SightRadar-native {"URL": ...} / {"GcsKey": ...}, and maps {"S3Object": {"Bucket","Name"}} to a public https://<bucket>.s3.amazonaws.com/<name> URL.
• compare_faces accepts URL/GcsKey images (not raw Bytes), matching the SightRadar /v1/compare contract.
• Deletion is soft by default. Rekognition's DeleteCollection is immediate and final; SightRadar's default is a restorable soft delete with an asynchronous purge (202). Pass Immediate=True (or Compliance=True for an audited GDPR/BIPA erasure) to match Rekognition's finality. The 202 body is under SightRadarRaw.
• Unsupported Rekognition ops (detect_labels, detect_text, recognize_celebrities, video ops, user-vector ops, delete_faces — use the per-photo delete endpoint instead, …) raise a clear NotImplementedError naming the limitation and the SightRadar alternative — they never silently no-op.
• Extra data isn't lost. Every response includes a SightRadarRaw key with the untranslated SightRadar payload.

Errors

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

License

MIT — see LICENSE.