Metadata-Version: 2.5
Name: sightradar-rekognition-shim
Version: 0.2.0
Summary: Drop-in shim that lets boto3 AWS Rekognition face-recognition code run against SightRadar with a ~2-line change.
Project-URL: Homepage, https://sightradar.com
Project-URL: Documentation, https://sightradar.com/docs
Project-URL: Source, https://github.com/sightradar/sdks/tree/main/python-rekognition-shim
Project-URL: Pricing, https://sightradar.com/pricing
Project-URL: Migrate from AWS Rekognition, https://sightradar.com/migrate
Author: SightRadar
License: MIT
License-File: LICENSE
Keywords: boto3,face-recognition,migration,rekognition,shim,sightradar
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# sightradar-rekognition-shim

A drop-in shim that lets code written against **AWS Rekognition** (via `boto3`)
run against **[SightRadar](https://sightradar.com)** 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

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

## The 2-line change

**Before — AWS Rekognition:**

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

```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.

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

## Mapped operations

| Rekognition method        | SightRadar endpoint                          |
| ------------------------- | -------------------------------------------- |
| `create_collection`       | `POST /v1/collections`                       |
| `delete_collection`       | `DELETE /v1/collections/{id}` (soft by default; `Immediate=True` / `Compliance=True` shim kwargs) |
| `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`                           |

## 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](./LICENSE).
