sightradar 1.0.0__tar.gz

sightradar-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Import + build smoke test
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+          python -c "import sys; sys.path.insert(0, 'src'); import sightradar; print('sightradar', sightradar.__version__)"

sightradar-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+# Publish to PyPI when a tag like `v1.0.0` is pushed.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # Trusted publishing to PyPI (OIDC) — no API token stored in the repo.
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

sightradar-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editor / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/

sightradar-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SightRadar (THIRDACT LABS PRIVATE LIMITED)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sightradar-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: sightradar
+Version: 1.0.0
+Summary: Official Python client for the SightRadar face recognition API
+Project-URL: Homepage, https://sightradar.com
+Project-URL: Documentation, https://sightradar.com/docs
+Project-URL: Source, https://github.com/sightradar-hq/sightradar-python
+Author: SightRadar
+License: MIT
+License-File: LICENSE
+Keywords: api,face recognition,facial recognition,rekognition,sightradar
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# SightRadar — Python client
+
+Official Python client for the [SightRadar](https://sightradar.com) face
+recognition API. Zero runtime dependencies (built on the standard library).
+
+```bash
+pip install sightradar
+```
+
+## Authenticate
+
+Create an API key in the [console](https://sightradar.com/login), then pass it
+directly or via the `SIGHTRADAR_API_KEY` environment variable.
+
+```python
+from sightradar import SightRadar
+
+sr = SightRadar(api_key="frs_...")   # or: SightRadar() with SIGHTRADAR_API_KEY set
+```
+
+## Core workflow
+
+```python
+# 1. Create a collection to hold faces.
+sr.create_collection("event-2026")
+
+# 2. Index faces from photos (URL, GCS key, or a local file).
+sr.index("event-2026", url="https://example.com/group.jpg")
+sr.index("event-2026", file="/path/to/photo.jpg", photo_id="img-42")
+
+# 3. Search the collection with one selfie.
+result = sr.search("event-2026", url="https://example.com/selfie.jpg")
+if result.found:
+    for m in result.matches:
+        print(m.photo_id, round(m.similarity, 3))
+else:
+    print("no match:", result.reason)
+```
+
+## Stateless operations (nothing stored)
+
+```python
+# Detect + quality-gate faces in an image.
+det = sr.detect(url="https://example.com/photo.jpg")
+print(det.detected_face_count, det.gated_face_count)
+
+# 1:1 verification between two faces.
+cmp = sr.compare(
+    source_url="https://example.com/a.jpg",
+    target_url="https://example.com/b.jpg",
+)
+print(cmp.match, cmp.similarity)
+```
+
+## Account
+
+```python
+print(sr.wallet().balance_credits)
+print(sr.usage(days=30))
+```
+
+## Errors
+
+Every non-2xx response raises a typed exception:
+
+```python
+from sightradar import (
+    SightRadarError,            # base
+    AuthenticationError,        # 401
+    InsufficientCreditsError,   # 402
+    NotFoundError,              # 404
+    RateLimitError,             # 429
+)
+
+try:
+    sr.describe_collection("missing")
+except NotFoundError as e:
+    print(e.status_code, e.message)
+```
+
+## Image inputs
+
+Index / search / detect / register-selfie accept exactly one image source:
+
+- `url=` — a public image URL
+- `gcs_key=` — a Google Cloud Storage object key
+- `file=` — a local path, `bytes`, or a file-like object (uploaded as multipart)
+
+`search` additionally accepts `embedding=` (a 512-d vector).
+
+## License
+
+MIT

sightradar-1.0.0/README.md

@@ -0,0 +1,93 @@
+# SightRadar — Python client
+
+Official Python client for the [SightRadar](https://sightradar.com) face
+recognition API. Zero runtime dependencies (built on the standard library).
+
+```bash
+pip install sightradar
+```
+
+## Authenticate
+
+Create an API key in the [console](https://sightradar.com/login), then pass it
+directly or via the `SIGHTRADAR_API_KEY` environment variable.
+
+```python
+from sightradar import SightRadar
+
+sr = SightRadar(api_key="frs_...")   # or: SightRadar() with SIGHTRADAR_API_KEY set
+```
+
+## Core workflow
+
+```python
+# 1. Create a collection to hold faces.
+sr.create_collection("event-2026")
+
+# 2. Index faces from photos (URL, GCS key, or a local file).
+sr.index("event-2026", url="https://example.com/group.jpg")
+sr.index("event-2026", file="/path/to/photo.jpg", photo_id="img-42")
+
+# 3. Search the collection with one selfie.
+result = sr.search("event-2026", url="https://example.com/selfie.jpg")
+if result.found:
+    for m in result.matches:
+        print(m.photo_id, round(m.similarity, 3))
+else:
+    print("no match:", result.reason)
+```
+
+## Stateless operations (nothing stored)
+
+```python
+# Detect + quality-gate faces in an image.
+det = sr.detect(url="https://example.com/photo.jpg")
+print(det.detected_face_count, det.gated_face_count)
+
+# 1:1 verification between two faces.
+cmp = sr.compare(
+    source_url="https://example.com/a.jpg",
+    target_url="https://example.com/b.jpg",
+)
+print(cmp.match, cmp.similarity)
+```
+
+## Account
+
+```python
+print(sr.wallet().balance_credits)
+print(sr.usage(days=30))
+```
+
+## Errors
+
+Every non-2xx response raises a typed exception:
+
+```python
+from sightradar import (
+    SightRadarError,            # base
+    AuthenticationError,        # 401
+    InsufficientCreditsError,   # 402
+    NotFoundError,              # 404
+    RateLimitError,             # 429
+)
+
+try:
+    sr.describe_collection("missing")
+except NotFoundError as e:
+    print(e.status_code, e.message)
+```
+
+## Image inputs
+
+Index / search / detect / register-selfie accept exactly one image source:
+
+- `url=` — a public image URL
+- `gcs_key=` — a Google Cloud Storage object key
+- `file=` — a local path, `bytes`, or a file-like object (uploaded as multipart)
+
+`search` additionally accepts `embedding=` (a 512-d vector).
+
+## License
+
+MIT

sightradar-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sightradar"
+version = "1.0.0"
+description = "Official Python client for the SightRadar face recognition API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "SightRadar" }]
+keywords = ["face recognition", "facial recognition", "api", "sightradar", "rekognition"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+# Zero runtime dependencies — built on the standard library.
+dependencies = []
+
+[project.urls]
+Homepage = "https://sightradar.com"
+Documentation = "https://sightradar.com/docs"
+Source = "https://github.com/sightradar-hq/sightradar-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sightradar"]

sightradar-1.0.0/src/sightradar/__init__.py

@@ -0,0 +1,53 @@
+"""SightRadar — official Python client for the face recognition API.
+
+Quickstart
+----------
+    from sightradar import SightRadar
+
+    sr = SightRadar(api_key="frs_...")          # or set SIGHTRADAR_API_KEY
+    sr.create_collection("event-2026")
+    sr.index("event-2026", url="https://example.com/group.jpg")
+    result = sr.search("event-2026", url="https://example.com/selfie.jpg")
+    for m in result.matches:
+        print(m.photo_id, m.similarity)
+
+The API is Rekognition-compatible in shape but exposed through a small, explicit
+surface here. Every call raises :class:`SightRadarError` on a non-2xx response.
+"""
+
+from .client import SightRadar
+from .errors import (
+    SightRadarError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import (
+    Collection,
+    SearchResult,
+    Match,
+    IndexResult,
+    CompareResult,
+    DetectResult,
+    Wallet,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "SightRadar",
+    "SightRadarError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "RateLimitError",
+    "Collection",
+    "SearchResult",
+    "Match",
+    "IndexResult",
+    "CompareResult",
+    "DetectResult",
+    "Wallet",
+    "__version__",
+]

sightradar-1.0.0/src/sightradar/client.py

@@ -0,0 +1,375 @@
+"""The synchronous SightRadar API client.
+
+Zero hard dependencies — built on the Python standard library (``urllib``) so it
+installs clean anywhere. File uploads use multipart/form-data; URL/GCS-key inputs
+use JSON.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import mimetypes
+import os
+import uuid
+from typing import Any, BinaryIO, Dict, List, Optional, Union
+from urllib import error as urlerror
+from urllib import request as urlrequest
+
+from .errors import SightRadarError, error_for_status
+from .models import (
+    Collection,
+    CompareResult,
+    DetectResult,
+    IndexResult,
+    SearchResult,
+    Wallet,
+)
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://api.sightradar.com"
+
+# A path-or-file the SDK can read bytes from for an upload.
+FileLike = Union[str, bytes, BinaryIO, io.IOBase]
+
+
+class SightRadar:
+    """Client for the SightRadar face recognition API.
+
+    Args:
+        api_key: Your ``frs_<prefix>_<secret>`` key. Falls back to the
+            ``SIGHTRADAR_API_KEY`` environment variable.
+        base_url: Override the API base (defaults to the production gateway).
+        timeout: Per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ):
+        key = api_key or os.environ.get("SIGHTRADAR_API_KEY")
+        if not key:
+            raise SightRadarError(
+                "No API key. Pass api_key=... or set SIGHTRADAR_API_KEY."
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # -- transport ----------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"sightradar-python/{__version__}",
+            "Accept": "application/json",
+        }
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[Dict[str, Any]] = None,
+        raw_body: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+        query: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        if query:
+            from urllib.parse import urlencode
+
+            params = {k: v for k, v in query.items() if v is not None}
+            if params:
+                url = f"{url}?{urlencode(params)}"
+
+        headers = self._headers()
+        data: Optional[bytes] = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif raw_body is not None:
+            data = raw_body
+            if content_type:
+                headers["Content-Type"] = content_type
+
+        req = urlrequest.Request(url, data=data, method=method, headers=headers)
+        try:
+            with urlrequest.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read()
+                return self._parse(resp.status, body)
+        except urlerror.HTTPError as e:
+            body = e.read()
+            self._raise(e.code, body)
+        except urlerror.URLError as e:  # network / DNS / TLS
+            raise SightRadarError(f"request failed: {e.reason}") from e
+
+    @staticmethod
+    def _parse(status: int, body: bytes) -> Any:
+        if not body:
+            return {}
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError:
+            raise SightRadarError(
+                f"non-JSON response (status {status})", status
+            )
+
+    @staticmethod
+    def _raise(status: int, body: bytes) -> None:
+        message = f"request failed ({status})"
+        try:
+            parsed = json.loads(body)
+            if isinstance(parsed, dict) and parsed.get("error"):
+                message = str(parsed["error"])
+        except (json.JSONDecodeError, ValueError):
+            if body:
+                message = body.decode("utf-8", "replace")[:300]
+        raise error_for_status(status, message)
+
+    # -- multipart ----------------------------------------------------------
+
+    def _multipart(
+        self, file: FileLike, fields: Optional[Dict[str, Any]] = None
+    ) -> tuple[bytes, str]:
+        """Build a multipart/form-data body from a file + optional fields."""
+        filename, content = _read_file(file)
+        boundary = f"----sightradar{uuid.uuid4().hex}"
+        ctype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        buf = io.BytesIO()
+
+        def w(s: str) -> None:
+            buf.write(s.encode("utf-8"))
+
+        for k, v in (fields or {}).items():
+            if v is None:
+                continue
+            w(f"--{boundary}\r\n")
+            w(f'Content-Disposition: form-data; name="{k}"\r\n\r\n')
+            w(f"{v}\r\n")
+
+        w(f"--{boundary}\r\n")
+        w(f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n')
+        w(f"Content-Type: {ctype}\r\n\r\n")
+        buf.write(content)
+        w(f"\r\n--{boundary}--\r\n")
+        return buf.getvalue(), f"multipart/form-data; boundary={boundary}"
+
+    # -- collections --------------------------------------------------------
+
+    def create_collection(self, collection_id: str) -> Collection:
+        """Create a collection. Idempotent-ish: a duplicate raises (409)."""
+        d = self._request(
+            "POST", "/v1/collections", json_body={"collection_id": collection_id}
+        )
+        return Collection.from_dict(d)
+
+    def list_collections(
+        self, *, q: Optional[str] = None, limit: int = 50, offset: int = 0
+    ) -> List[Collection]:
+        """List your collections (server-side searchable via ``q``)."""
+        d = self._request(
+            "GET",
+            "/v1/collections",
+            query={"q": q, "limit": limit, "offset": offset},
+        )
+        items = d.get("collections", d) if isinstance(d, dict) else d
+        return [Collection.from_dict(c) for c in (items or [])]
+
+    def describe_collection(self, collection_id: str) -> Collection:
+        d = self._request("GET", f"/v1/collections/{collection_id}")
+        return Collection.from_dict(d)
+
+    def delete_collection(self, collection_id: str) -> Dict[str, Any]:
+        """Delete a collection and CASCADE every stored face/selfie. Irreversible."""
+        return self._request("DELETE", f"/v1/collections/{collection_id}")
+
+    # -- index / search -----------------------------------------------------
+
+    def index(
+        self,
+        collection_id: str,
+        *,
+        url: Optional[str] = None,
+        gcs_key: Optional[str] = None,
+        photo_id: Optional[str] = None,
+        file: Optional[FileLike] = None,
+    ) -> IndexResult:
+        """Detect, embed, and store every face in a photo.
+
+        Provide exactly one image source: ``url``, ``gcs_key``, or ``file``.
+        """
+        path = f"/v1/collections/{collection_id}/index"
+        if file is not None:
+            body, ctype = self._multipart(file, {"photoId": photo_id})
+            d = self._request("POST", path, raw_body=body, content_type=ctype)
+        else:
+            d = self._request(
+                "POST", path, json_body=_image_body(url, gcs_key, photo_id)
+            )
+        return IndexResult.from_dict(d)
+
+    def search(
+        self,
+        collection_id: str,
+        *,
+        url: Optional[str] = None,
+        gcs_key: Optional[str] = None,
+        embedding: Optional[List[float]] = None,
+        file: Optional[FileLike] = None,
+        threshold: Optional[float] = None,
+        limit: Optional[int] = None,
+    ) -> SearchResult:
+        """Find every stored photo a person appears in, from one selfie.
+
+        Provide one of ``url``, ``gcs_key``, ``embedding``, or ``file``.
+        """
+        path = f"/v1/collections/{collection_id}/search"
+        if file is not None:
+            body, ctype = self._multipart(
+                file, {"threshold": threshold, "limit": limit}
+            )
+            d = self._request("POST", path, raw_body=body, content_type=ctype)
+        else:
+            payload: Dict[str, Any] = {}
+            if embedding is not None:
+                payload["embedding"] = embedding
+            elif url is not None:
+                payload["url"] = url
+            elif gcs_key is not None:
+                payload["gcsKey"] = gcs_key
+            else:
+                raise SightRadarError(
+                    "search needs one of: url, gcs_key, embedding, or file"
+                )
+            if threshold is not None:
+                payload["threshold"] = threshold
+            if limit is not None:
+                payload["limit"] = limit
+            d = self._request("POST", path, json_body=payload)
+        return SearchResult.from_dict(d)
+
+    def search_by_id(
+        self,
+        collection_id: str,
+        point_id: str,
+        *,
+        threshold: Optional[float] = None,
+        limit: Optional[int] = None,
+    ) -> SearchResult:
+        """Search using a previously-stored selfie point id."""
+        payload: Dict[str, Any] = {"id": point_id}
+        if threshold is not None:
+            payload["threshold"] = threshold
+        if limit is not None:
+            payload["limit"] = limit
+        d = self._request(
+            "POST", f"/v1/collections/{collection_id}/search-by-id", json_body=payload
+        )
+        return SearchResult.from_dict(d)
+
+    def register_selfie(
+        self,
+        collection_id: str,
+        *,
+        url: Optional[str] = None,
+        gcs_key: Optional[str] = None,
+        file: Optional[FileLike] = None,
+        photo_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Register a selfie point you can later search by id."""
+        path = f"/v1/collections/{collection_id}/selfies"
+        if file is not None:
+            body, ctype = self._multipart(file, {"photoId": photo_id})
+            return self._request("POST", path, raw_body=body, content_type=ctype)
+        return self._request("POST", path, json_body=_image_body(url, gcs_key, photo_id))
+
+    # -- stateless ops ------------------------------------------------------
+
+    def detect(
+        self,
+        *,
+        url: Optional[str] = None,
+        gcs_key: Optional[str] = None,
+        file: Optional[FileLike] = None,
+    ) -> DetectResult:
+        """Locate and quality-gate faces in an image. Nothing is stored."""
+        if file is not None:
+            body, ctype = self._multipart(file)
+            d = self._request("POST", "/v1/detect", raw_body=body, content_type=ctype)
+        else:
+            d = self._request("POST", "/v1/detect", json_body=_image_body(url, gcs_key))
+        return DetectResult.from_dict(d)
+
+    def compare(
+        self,
+        *,
+        source_url: Optional[str] = None,
+        target_url: Optional[str] = None,
+        source_gcs_key: Optional[str] = None,
+        target_gcs_key: Optional[str] = None,
+        source_embedding: Optional[List[float]] = None,
+        target_embedding: Optional[List[float]] = None,
+    ) -> CompareResult:
+        """1:1 similarity / verification between two faces. Nothing is stored."""
+        payload: Dict[str, Any] = {}
+        if source_url:
+            payload["sourceUrl"] = source_url
+        if target_url:
+            payload["targetUrl"] = target_url
+        if source_gcs_key:
+            payload["sourceGcsKey"] = source_gcs_key
+        if target_gcs_key:
+            payload["targetGcsKey"] = target_gcs_key
+        if source_embedding is not None:
+            payload["source_embedding"] = source_embedding
+        if target_embedding is not None:
+            payload["target_embedding"] = target_embedding
+        d = self._request("POST", "/v1/compare", json_body=payload)
+        return CompareResult.from_dict(d)
+
+    # -- account ------------------------------------------------------------
+
+    def wallet(self) -> Wallet:
+        """Get the current credit balance."""
+        return Wallet.from_dict(self._request("GET", "/v1/wallet"))
+
+    def usage(self, days: int = 30) -> Dict[str, Any]:
+        """Usage report aggregated from the ledger."""
+        return self._request("GET", "/v1/usage", query={"days": days})
+
+
+# -- helpers ----------------------------------------------------------------
+
+
+def _image_body(
+    url: Optional[str], gcs_key: Optional[str], photo_id: Optional[str] = None
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {}
+    if url:
+        body["url"] = url
+    elif gcs_key:
+        body["gcsKey"] = gcs_key
+    else:
+        raise SightRadarError("provide one of: url, gcs_key, or file")
+    if photo_id:
+        body["photoId"] = photo_id
+    return body
+
+
+def _read_file(file: FileLike) -> tuple[str, bytes]:
+    """Resolve a path / bytes / file-object into (filename, content_bytes)."""
+    if isinstance(file, str):
+        with open(file, "rb") as fh:
+            return os.path.basename(file), fh.read()
+    if isinstance(file, (bytes, bytearray)):
+        return "upload.jpg", bytes(file)
+    # file-like object
+    name = getattr(file, "name", "upload.jpg")
+    content = file.read()
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+    return os.path.basename(str(name)), content

sightradar-1.0.0/src/sightradar/errors.py

@@ -0,0 +1,53 @@
+"""Exception types raised by the SightRadar client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SightRadarError(Exception):
+    """Base error for all non-2xx API responses and transport failures.
+
+    Attributes:
+        message: Human-readable error message (from the API ``error`` field when present).
+        status_code: HTTP status code, or ``None`` for transport-level failures.
+    """
+
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        if self.status_code is not None:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(SightRadarError):
+    """Raised on 401 — the API key is missing, malformed, or revoked."""
+
+
+class InsufficientCreditsError(SightRadarError):
+    """Raised on 402 — the wallet does not have enough credits for the operation."""
+
+
+class NotFoundError(SightRadarError):
+    """Raised on 404 — the collection, key, or resource does not exist."""
+
+
+class RateLimitError(SightRadarError):
+    """Raised on 429 — too many requests; back off and retry."""
+
+
+def error_for_status(status_code: int, message: str) -> SightRadarError:
+    """Map an HTTP status to the most specific error subclass."""
+    if status_code == 401:
+        return AuthenticationError(message, status_code)
+    if status_code == 402:
+        return InsufficientCreditsError(message, status_code)
+    if status_code == 404:
+        return NotFoundError(message, status_code)
+    if status_code == 429:
+        return RateLimitError(message, status_code)
+    return SightRadarError(message, status_code)

sightradar-1.0.0/src/sightradar/models.py

@@ -0,0 +1,148 @@
+"""Typed response models.
+
+These are lightweight dataclasses built from the JSON the API returns. Each has
+a ``from_dict`` constructor that is tolerant of unknown/extra fields (forward
+compatible) and exposes the raw payload via ``.raw`` for anything not modelled.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Collection:
+    collection_id: str
+    status: str
+    photo_count: int = 0
+    face_count: int = 0
+    selfie_count: int = 0
+    created_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Collection":
+        return cls(
+            collection_id=d.get("collection_id", ""),
+            status=d.get("status", ""),
+            photo_count=d.get("photo_count", 0) or 0,
+            face_count=d.get("face_count", 0) or 0,
+            selfie_count=d.get("selfie_count", 0) or 0,
+            created_at=d.get("created_at"),
+            raw=d,
+        )
+
+
+@dataclass
+class Match:
+    photo_id: Optional[str] = None
+    similarity: Optional[float] = None
+    point_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Match":
+        return cls(
+            photo_id=d.get("photo_id") or d.get("photoId"),
+            similarity=d.get("similarity"),
+            point_id=d.get("point_id") or d.get("id"),
+            raw=d,
+        )
+
+
+@dataclass
+class SearchResult:
+    collection_id: str = ""
+    matches: List[Match] = field(default_factory=list)
+    photo_ids: List[str] = field(default_factory=list)
+    reason: Optional[str] = None
+    model_version: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def found(self) -> bool:
+        """True when at least one match was returned."""
+        return len(self.matches) > 0
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "SearchResult":
+        return cls(
+            collection_id=d.get("collection_id", ""),
+            matches=[Match.from_dict(m) for m in d.get("matches", []) or []],
+            photo_ids=list(d.get("photo_ids", []) or []),
+            reason=d.get("reason"),
+            model_version=d.get("model_version"),
+            raw=d,
+        )
+
+
+@dataclass
+class IndexResult:
+    collection_id: str = ""
+    photo_id: Optional[str] = None
+    indexed: int = 0
+    detected_face_count: int = 0
+    rejected_face_count: int = 0
+    faces: List[Dict[str, Any]] = field(default_factory=list)
+    model_version: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "IndexResult":
+        return cls(
+            collection_id=d.get("collection_id", ""),
+            photo_id=d.get("photo_id") or d.get("photoId"),
+            indexed=d.get("indexed", 0) or 0,
+            detected_face_count=d.get("detected_face_count", 0) or 0,
+            rejected_face_count=d.get("rejected_face_count", 0) or 0,
+            faces=list(d.get("faces", []) or []),
+            model_version=d.get("model_version"),
+            raw=d,
+        )
+
+
+@dataclass
+class CompareResult:
+    face_found: bool = False
+    similarity: Optional[float] = None
+    match: bool = False
+    threshold: Optional[float] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "CompareResult":
+        return cls(
+            face_found=bool(d.get("face_found", False)),
+            similarity=d.get("similarity"),
+            match=bool(d.get("match", False)),
+            threshold=d.get("threshold"),
+            raw=d,
+        )
+
+
+@dataclass
+class DetectResult:
+    detected_face_count: int = 0
+    gated_face_count: int = 0
+    faces: List[Dict[str, Any]] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "DetectResult":
+        return cls(
+            detected_face_count=d.get("detected_face_count", 0) or 0,
+            gated_face_count=d.get("gated_face_count", 0) or 0,
+            faces=list(d.get("faces", []) or []),
+            raw=d,
+        )
+
+
+@dataclass
+class Wallet:
+    balance_credits: int = 0
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Wallet":
+        return cls(balance_credits=d.get("balance_credits", 0) or 0, raw=d)