authentasdk 0.2.8__tar.gz → 0.2.9__tar.gz

{authentasdk-0.2.8 → authentasdk-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authentasdk
-Version: 0.2.8
+Version: 0.2.9
 Summary: Python SDK for the Authenta API to detect deepfakes and manipulated media
 Home-page: https://github.com/phospheneai/authenta-python-sdk
 Author: Arjun Adhithya
@@ -32,7 +32,8 @@ Welcome to the official documentation for the **Authenta Python SDK** — your g
    - [4.3 FI-1 — Face Intelligence](#43-fi-1--face-intelligence)
    - [4.4 FE-1 — Face Embedding](#44-fe-1--face-embedding)
    - [4.5 DI-1 — Document Forgery Detection](#45-di-1--document-forgery-detection)
-   - [4.6 Media Management](#46-media-management)
+   - [4.6 Face Indexing](#46-face-indexing)
+   - [4.7 Media Management](#47-media-management)
 5. [Visualization](#5-visualization)
 6. [Error Handling](#6-error-handling)
 7. [API Reference](#7-api-reference)
@@ -650,7 +651,89 @@ asyncio.run(detect_document())
 
 ---
 
-### 4.6 Media Management
+### 4.6 Face Indexing
+
+Index a person's photos, then find that face again later. This is separate from
+the detection models — it runs no FI-1/DF-1/AC-1 job, and uses three endpoints
+on the same host and API key:
+
+| Method | Endpoint |
+|---|---|
+| `faceEnroll(images)` | `POST /api/v1/facesim/v1/enroll` |
+| `tenants()` | `GET /api/v1/facesim/v1/subjects` |
+| `faceSearch(image, limit)` | `POST /api/v1/facesim/v1/search` |
+
+#### Enrol a face
+
+```python
+enrolled = client.faceEnroll([
+    "data_samples/face_similiar/person_1/A.jpeg",
+    "data_samples/face_similiar/person_1/B.jpeg",
+])
+
+print(enrolled["subject_id"])
+for face in enrolled["faces"]:
+    print(face["face_id"], face["status"])   # "uploaded" or "failed"
+```
+
+Accepts **1–10 images** of the same person, and only **JPEG, PNG, or WebP**.
+Every file is validated before anything is sent, so a bad path never leaves a
+half-built subject on the server.
+
+`faceEnroll` returns as soon as the photos reach S3. The embeddings are
+generated in the background, so each face comes back as `uploaded`, not
+`processed` — poll `tenants()` to see them settle. One failed upload marks only
+its own face rather than sinking the batch.
+
+#### Check indexing progress
+
+```python
+for subject in client.tenants()["subjects"]:
+    for face in subject["faces"]:
+        print(subject["subject_id"], face["name"], face["status"], face["error"])
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | Upload URL created; the object has not been acknowledged yet |
+| `uploaded` | Stored; waiting for a worker |
+| `processing` | A worker is generating the embedding |
+| `processed` | Embedding stored — the face is searchable |
+| `failed` | Upload validation or embedding failed — see `error` |
+
+Only `processed` faces are searched, so searching too early returns `count: 0`.
+
+#### Search a face
+
+```python
+matches = client.faceSearch("data_samples/face_similiar/person_1/A.jpeg", limit=10)
+
+print(matches["count"])
+for match in matches["results"]:
+    print(match["rank"], match["subject_id"], match["similarity_score"])
+```
+
+The photo is posted as `multipart/form-data` rather than Base64 in a JSON body,
+which keeps it clear of the server's 100 KiB JSON limit. `limit` is clamped to
+1–50 and defaults to 50.
+
+Search is independent of enrolment: it matches everything already indexed on the
+account, including from earlier sessions. The same subject can appear more than
+once because every enrolled face has its own embedding, and results run from
+highest similarity down.
+
+Unsupported formats are converted to JPEG when **Pillow** is installed
+(`pip install Pillow`); without it you get a clear `ValidationError` instead of
+a server-side `invalid_image`. The conversion also bakes any EXIF rotation into
+the pixels — an image left with a stale orientation tag is read sideways by face
+detection and comes back as `no_face_detected`.
+
+A full runnable script lives in
+[`examples/test_face_indexing.py`](examples/test_face_indexing.py).
+
+---
+
+### 4.7 Media Management
 
 #### Get Media
 
@@ -960,6 +1043,40 @@ Raises `ValueError` if no result artifact is found.
 
 ---
 
+#### `faceEnroll(images) -> Dict`
+
+Enrol 1–10 photos of one person: creates the subject, then uploads each image
+to its presigned S3 URL.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `images` | `list[str]` | Local paths. JPEG, PNG, or WebP only |
+
+Returns the enroll response — `subject_id`, `status`, and a `faces` array whose
+`status` is set to `uploaded` or `failed` per image. Embeddings follow out of
+band; poll `tenants()` for `processed`.
+
+Raises `ValidationError` for an empty list, more than 10 images, a missing file,
+or an unsupported image type — all checked before any request is sent.
+
+#### `tenants() -> Dict`
+
+Every subject and face on the account: `{"tenant_id", "subjects"}`, where each
+subject holds `face_id`, `name`, `status`, `embedding`, `image_url`, and `error`.
+
+#### `faceSearch(image, limit=50, timeout=120.0) -> Dict`
+
+Rank enrolled faces against a query photo, posted as `multipart/form-data`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `image` | `str` | — | Local path to the query photo |
+| `limit` | `int` | `50` | Matches to return, clamped to 1–50 |
+| `timeout` | `float` | `120.0` | Seconds — embedding takes longer than a plain request |
+
+Returns `{"tenant_id", "count", "results"}` with results ordered from highest
+similarity down. Only faces with `status: "processed"` are searched.
+
 #### `get_media(jobid) -> Dict`
 
 `GET /api/v1/jobs/{jobid}` — fetch the current state of a media record.

{authentasdk-0.2.8 → authentasdk-0.2.9}/README.md

@@ -15,7 +15,8 @@ Welcome to the official documentation for the **Authenta Python SDK** — your g
    - [4.3 FI-1 — Face Intelligence](#43-fi-1--face-intelligence)
    - [4.4 FE-1 — Face Embedding](#44-fe-1--face-embedding)
    - [4.5 DI-1 — Document Forgery Detection](#45-di-1--document-forgery-detection)
-   - [4.6 Media Management](#46-media-management)
+   - [4.6 Face Indexing](#46-face-indexing)
+   - [4.7 Media Management](#47-media-management)
 5. [Visualization](#5-visualization)
 6. [Error Handling](#6-error-handling)
 7. [API Reference](#7-api-reference)
@@ -633,7 +634,89 @@ asyncio.run(detect_document())
 
 ---
 
-### 4.6 Media Management
+### 4.6 Face Indexing
+
+Index a person's photos, then find that face again later. This is separate from
+the detection models — it runs no FI-1/DF-1/AC-1 job, and uses three endpoints
+on the same host and API key:
+
+| Method | Endpoint |
+|---|---|
+| `faceEnroll(images)` | `POST /api/v1/facesim/v1/enroll` |
+| `tenants()` | `GET /api/v1/facesim/v1/subjects` |
+| `faceSearch(image, limit)` | `POST /api/v1/facesim/v1/search` |
+
+#### Enrol a face
+
+```python
+enrolled = client.faceEnroll([
+    "data_samples/face_similiar/person_1/A.jpeg",
+    "data_samples/face_similiar/person_1/B.jpeg",
+])
+
+print(enrolled["subject_id"])
+for face in enrolled["faces"]:
+    print(face["face_id"], face["status"])   # "uploaded" or "failed"
+```
+
+Accepts **1–10 images** of the same person, and only **JPEG, PNG, or WebP**.
+Every file is validated before anything is sent, so a bad path never leaves a
+half-built subject on the server.
+
+`faceEnroll` returns as soon as the photos reach S3. The embeddings are
+generated in the background, so each face comes back as `uploaded`, not
+`processed` — poll `tenants()` to see them settle. One failed upload marks only
+its own face rather than sinking the batch.
+
+#### Check indexing progress
+
+```python
+for subject in client.tenants()["subjects"]:
+    for face in subject["faces"]:
+        print(subject["subject_id"], face["name"], face["status"], face["error"])
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | Upload URL created; the object has not been acknowledged yet |
+| `uploaded` | Stored; waiting for a worker |
+| `processing` | A worker is generating the embedding |
+| `processed` | Embedding stored — the face is searchable |
+| `failed` | Upload validation or embedding failed — see `error` |
+
+Only `processed` faces are searched, so searching too early returns `count: 0`.
+
+#### Search a face
+
+```python
+matches = client.faceSearch("data_samples/face_similiar/person_1/A.jpeg", limit=10)
+
+print(matches["count"])
+for match in matches["results"]:
+    print(match["rank"], match["subject_id"], match["similarity_score"])
+```
+
+The photo is posted as `multipart/form-data` rather than Base64 in a JSON body,
+which keeps it clear of the server's 100 KiB JSON limit. `limit` is clamped to
+1–50 and defaults to 50.
+
+Search is independent of enrolment: it matches everything already indexed on the
+account, including from earlier sessions. The same subject can appear more than
+once because every enrolled face has its own embedding, and results run from
+highest similarity down.
+
+Unsupported formats are converted to JPEG when **Pillow** is installed
+(`pip install Pillow`); without it you get a clear `ValidationError` instead of
+a server-side `invalid_image`. The conversion also bakes any EXIF rotation into
+the pixels — an image left with a stale orientation tag is read sideways by face
+detection and comes back as `no_face_detected`.
+
+A full runnable script lives in
+[`examples/test_face_indexing.py`](examples/test_face_indexing.py).
+
+---
+
+### 4.7 Media Management
 
 #### Get Media
 
@@ -943,6 +1026,40 @@ Raises `ValueError` if no result artifact is found.
 
 ---
 
+#### `faceEnroll(images) -> Dict`
+
+Enrol 1–10 photos of one person: creates the subject, then uploads each image
+to its presigned S3 URL.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `images` | `list[str]` | Local paths. JPEG, PNG, or WebP only |
+
+Returns the enroll response — `subject_id`, `status`, and a `faces` array whose
+`status` is set to `uploaded` or `failed` per image. Embeddings follow out of
+band; poll `tenants()` for `processed`.
+
+Raises `ValidationError` for an empty list, more than 10 images, a missing file,
+or an unsupported image type — all checked before any request is sent.
+
+#### `tenants() -> Dict`
+
+Every subject and face on the account: `{"tenant_id", "subjects"}`, where each
+subject holds `face_id`, `name`, `status`, `embedding`, `image_url`, and `error`.
+
+#### `faceSearch(image, limit=50, timeout=120.0) -> Dict`
+
+Rank enrolled faces against a query photo, posted as `multipart/form-data`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `image` | `str` | — | Local path to the query photo |
+| `limit` | `int` | `50` | Matches to return, clamped to 1–50 |
+| `timeout` | `float` | `120.0` | Seconds — embedding takes longer than a plain request |
+
+Returns `{"tenant_id", "count", "results"}` with results ordered from highest
+similarity down. Only faces with `status: "processed"` are searched.
+
 #### `get_media(jobid) -> Dict`
 
 `GET /api/v1/jobs/{jobid}` — fetch the current state of a media record.

{authentasdk-0.2.8 → authentasdk-0.2.9}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = authentasdk
-version = 0.2.8
+version = 0.2.9
 description = Python SDK for the Authenta API to detect deepfakes and manipulated media
 author = Arjun Adhithya
 author_email = rrarjunadhithya@gmail.com

{authentasdk-0.2.8 → authentasdk-0.2.9}/src/authenta/authenta_client.py

@@ -21,6 +21,12 @@ from .authenta_exceptions import (
     ValidationError,
     ServerError,
 )
+from .face_auth import (
+    BASE as FACESIM_BASE,
+    MAX_SEARCH_LIMIT,
+    FaceAuth,
+    clamp_limit,
+)
 
 def _raise_for_authenta_error(resp: requests.Response) -> None:
     """
@@ -101,18 +107,23 @@ class AuthentaClient:
         Create new Authenta client.
 
         Args:
-            base_url: Authenta API base URL, e.g. "https://platform/.authenta.ai".
+            base_url: Authenta API base URL, e.g. "https://platform.authenta.ai".
             api_key: Your Authenta API key.
         """
         self.base_url = base_url.rstrip("/")
         self.api_key = api_key
         self.auth_enabled = bool(api_key)
 
-    def _headers(self) -> Dict[str, str]:
-        """Return default headers for Authenta API calls."""
-        headers = {
-            "Content-Type": "application/json",
-        }
+    def _headers(self, content_type: Optional[str] = "application/json") -> Dict[str, str]:
+        """
+        Return default headers for Authenta API calls.
+
+        Pass ``content_type=None`` for multipart uploads — requests generates
+        the boundary itself, and setting the header by hand breaks it.
+        """
+        headers = {}
+        if content_type:
+            headers["Content-Type"] = content_type
         if self.auth_enabled:
             headers["Authorization"] = f"Bearer {self.api_key}"
 
@@ -376,6 +387,124 @@ class AuthentaClient:
         
         return media
 
+
+    # ── Face indexing ──────────────────────────────────────────────────────
+    # Three endpoints on this same host and API key. See face_auth.py.
+
+    def faceEnroll(self, images: list) -> Dict[str, Any]:
+        """
+        Enrol photos of one person: create the subject, then upload each image.
+
+        Returns as soon as S3 has the bytes. Embeddings are generated out of
+        band, so call :meth:`tenants` afterwards to watch each face reach
+        ``processed``.
+
+        Args:
+            images: Local paths to 1-10 photos of the same person. Only
+                    JPEG, PNG, and WebP are accepted.
+
+        Returns:
+            The enroll response, with each face's ``status`` updated to
+            ``uploaded`` or ``failed`` to reflect its own upload outcome.
+        """
+        face_auth = FaceAuth()
+        described_images = face_auth.EnrollFace(images)
+
+        resp = requests.post(
+            f"{self.base_url}{FACESIM_BASE}/enroll",
+            json={"images": described_images},
+            headers=self._headers(),
+            timeout=30,
+        )
+        if not resp.ok:
+            _raise_for_authenta_error(resp)
+        enrollment = _safe_json(resp)
+
+        faces = enrollment.get("faces", [])
+        if len(faces) != len(images):
+            raise RuntimeError(
+                f"Enrollment returned {len(faces)} upload URLs for {len(images)} images"
+            )
+
+        # The response preserves the order of `images`. One failed PUT marks
+        # only its own face, rather than sinking the whole batch.
+        for face, image, described in zip(faces, images, described_images):
+            upload_url = face.get("upload_url")
+            if not upload_url:
+                face["status"] = "failed"
+                continue
+
+            content_type = (face.get("headers") or {}).get(
+                "Content-Type", described["contentType"]
+            )
+            print(f"Uploading {os.path.basename(image)}...")
+            status = face_auth.putSignedUrl(upload_url, image, content_type)
+            face["status"] = "uploaded" if 200 <= status < 300 else "failed"
+
+        return enrollment
+
+    def tenants(self) -> Dict[str, Any]:
+        """
+        GET /api/v1/facesim/v1/subjects: every subject and face on the account.
+
+        Use it to follow enrolment progress — a face is searchable once its
+        status reaches ``processed``.
+        """
+        resp = requests.get(
+            f"{self.base_url}{FACESIM_BASE}/tenant",
+            headers=self._headers(),
+            timeout=30,
+        )
+        if not resp.ok:
+            _raise_for_authenta_error(resp)
+        return _safe_json(resp)
+
+    def faceSearch(
+        self,
+        image: str,
+        limit: int = MAX_SEARCH_LIMIT,
+        timeout: float = 120.0,
+    ) -> Dict[str, Any]:
+        """
+        POST /api/v1/facesim/v1/search: rank enrolled faces against a photo.
+
+        The image is posted as ``multipart/form-data`` rather than Base64 in a
+        JSON body, which keeps it clear of the server's 100 KiB JSON limit.
+
+        Search is independent of enrolment: it matches everything already
+        indexed on the account, including from earlier sessions. The same
+        subject can appear more than once because every enrolled face has its
+        own embedding.
+
+        Args:
+            image: Local path to the query photo.
+            limit: How many matches to return, clamped to 1-50.
+            timeout: Seconds to wait — embedding a face takes longer than a
+                     plain request.
+
+        Returns:
+            ``{"tenant_id", "count", "results"}`` with results ordered from
+            highest similarity down.
+        """
+        face_auth = FaceAuth()
+        path, content_type = face_auth.prepare_search_image(image)
+        capped = clamp_limit(limit)
+
+        print(f"Searching faces with {os.path.basename(path)} (limit {capped})...")
+        with open(path, "rb") as handle:
+            resp = requests.post(
+                f"{self.base_url}{FACESIM_BASE}/search",
+                # No Content-Type header here: requests sets the multipart
+                # boundary itself, and overriding it breaks the upload.
+                headers=self._headers(content_type=None),
+                files={"image": (os.path.basename(path), handle, content_type)},
+                data={"limit": str(capped)},
+                timeout=timeout,
+            )
+        if not resp.ok:
+            _raise_for_authenta_error(resp)
+        return _safe_json(resp)
+
     def get_result(self, media: Dict[str, Any]) -> Dict[str, Any]:
         """
         Fetch the detection result JSON from the media's resultURL.

authentasdk-0.2.9/src/authenta/face_auth.py

@@ -0,0 +1,176 @@
+"""
+Face indexing helpers — enrol faces, list subjects, search a face.
+
+Mirrors ``packages/core/src/core/faceauth.ts`` in the React Native SDK. Three
+endpoints, all on the same host and API key as the rest of the platform:
+
+    POST /api/v1/facesim/v1/enroll     create a subject + presigned upload URLs
+    GET  /api/v1/facesim/v1/subjects   every subject and face
+    POST /api/v1/facesim/v1/search     rank enrolled faces against a photo
+
+The functions here do the local work — validating files, deriving names and
+content types, uploading to S3. The HTTP calls live on
+``AuthentaClient.faceEnroll`` / ``faceSearch`` / ``tenants``.
+"""
+
+import mimetypes
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+import requests
+
+from .authenta_exceptions import ValidationError
+
+# ── Contract limits, matching the React Native SDK ──────────────────────────
+
+BASE = "/api/v1/facesim/v1"
+
+#: Content types the face indexing service can decode.
+SUPPORTED_FACE_IMAGE_TYPES = ("image/jpeg", "image/png", "image/webp")
+
+#: Enrollment accepts between 1 and 10 images per subject.
+MIN_ENROLL_IMAGES = 1
+MAX_ENROLL_IMAGES = 10
+
+#: Search returns at most 50 ranked faces.
+MAX_SEARCH_LIMIT = 50
+
+#: A face has settled once it can no longer change.
+TERMINAL_FACE_STATUSES = ("processed", "failed")
+
+
+def guess_content_type(path: str) -> str:
+    """Guess the MIME type of a file from its name."""
+    content_type, _ = mimetypes.guess_type(path)
+    return (content_type or "application/octet-stream").lower()
+
+
+def describe_image(image: str) -> Dict[str, str]:
+    """
+    Build the ``{"name", "contentType"}`` descriptor the enroll endpoint expects.
+
+    The full file name is kept — including the extension — because the server
+    uses it to label the face, and the content type is derived from it.
+
+    Raises:
+        ValidationError: if the file is missing, unnamed, or an unsupported type.
+    """
+    if not isinstance(image, str) or not image.strip():
+        raise ValidationError("Image path must be a non-empty string.")
+    if not os.path.isfile(image):
+        raise ValidationError(f"Image file does not exist: {image}")
+
+    name = os.path.basename(image).strip()
+    if not name or len(name) > 255:
+        raise ValidationError(f'Image name must be 1-255 characters - received: "{name}"')
+
+    content_type = guess_content_type(name)
+    if content_type not in SUPPORTED_FACE_IMAGE_TYPES:
+        raise ValidationError(
+            f'Unsupported image type "{content_type}" for {name}. '
+            f"Face indexing accepts {', '.join(SUPPORTED_FACE_IMAGE_TYPES)}."
+        )
+
+    return {"name": name, "contentType": content_type}
+
+
+def image_basename(image: str) -> Dict[str, str]:
+    """Backwards-compatible alias of :func:`describe_image`."""
+    return describe_image(image)
+
+
+def clamp_limit(limit: Optional[int]) -> int:
+    """Clamp a search limit into the 1-50 range the API accepts."""
+    try:
+        value = int(limit)
+    except (TypeError, ValueError):
+        value = MAX_SEARCH_LIMIT
+    return max(1, min(value, MAX_SEARCH_LIMIT))
+
+
+class FaceAuth:
+    """Local file handling for the face indexing endpoints."""
+
+    def EnrollFace(self, images: List[str]) -> List[Dict[str, str]]:
+        """
+        Validate the images and build the ``images`` array for ``POST /enroll``.
+
+        Every file is checked before anything is sent, so a bad path fails
+        before it can leave a half-built subject on the server.
+
+        Args:
+            images: Local paths to 1-10 photos of the same person.
+
+        Returns:
+            One ``{"name", "contentType"}`` descriptor per image, in order.
+        """
+        if not isinstance(images, (list, tuple)):
+            raise ValidationError("images must be a list of file paths.")
+        if len(images) < MIN_ENROLL_IMAGES or len(images) > MAX_ENROLL_IMAGES:
+            raise ValidationError(
+                f"Enrollment accepts {MIN_ENROLL_IMAGES}-{MAX_ENROLL_IMAGES} images "
+                f"- received {len(images)}."
+            )
+
+        return [describe_image(image) for image in images]
+
+    def putSignedUrl(
+        self,
+        url: str,
+        image: str,
+        content_type: Optional[str] = None,
+    ) -> int:
+        """
+        PUT one image to its presigned S3 URL.
+
+        The ``Content-Type`` must match the one the enroll response returned, or
+        S3 rejects the signature with 403.
+
+        Returns:
+            The HTTP status code from S3.
+        """
+        headers = {"Content-Type": content_type or guess_content_type(image)}
+        with open(image, "rb") as handle:
+            response = requests.put(url, data=handle, headers=headers, timeout=300)
+        return response.status_code
+
+    def prepare_search_image(self, image: str) -> Tuple[str, str]:
+        """
+        Check a query photo and report how to send it.
+
+        Unsupported formats (HEIC, TIFF, ...) are converted to JPEG when Pillow
+        is installed; without Pillow the caller gets a clear error instead of a
+        server-side ``invalid_image``.
+
+        Returns:
+            ``(path, content_type)`` ready for a multipart upload.
+        """
+        if not isinstance(image, str) or not image.strip():
+            raise ValidationError("A query image is required to search faces.")
+        if not os.path.isfile(image):
+            raise ValidationError(f"Image file does not exist: {image}")
+
+        content_type = guess_content_type(image)
+        if content_type in SUPPORTED_FACE_IMAGE_TYPES:
+            return image, content_type
+
+        try:
+            from PIL import Image  # optional dependency
+        except ImportError:
+            raise ValidationError(
+                f'Unsupported image type "{content_type}" for {os.path.basename(image)}. '
+                f"Face indexing accepts {', '.join(SUPPORTED_FACE_IMAGE_TYPES)} - "
+                "install Pillow to convert other formats automatically."
+            )
+
+        converted = f"{os.path.splitext(image)[0]}.authenta.jpg"
+        with Image.open(image) as handle:
+            # Convert to RGB and save: this also bakes any EXIF rotation into
+            # the pixels, which is what face detection relies on.
+            handle.convert("RGB").save(converted, "JPEG", quality=95)
+        return converted, "image/jpeg"
+
+    def search_files(self, image: str) -> Dict[str, Any]:
+        """Build the ``files=`` mapping for a multipart search request."""
+        path, content_type = self.prepare_search_image(image)
+        return {"path": path, "content_type": content_type}

{authentasdk-0.2.8 → authentasdk-0.2.9}/src/authentasdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: authentasdk
-Version: 0.2.8
+Version: 0.2.9
 Summary: Python SDK for the Authenta API to detect deepfakes and manipulated media
 Home-page: https://github.com/phospheneai/authenta-python-sdk
 Author: Arjun Adhithya
@@ -32,7 +32,8 @@ Welcome to the official documentation for the **Authenta Python SDK** — your g
    - [4.3 FI-1 — Face Intelligence](#43-fi-1--face-intelligence)
    - [4.4 FE-1 — Face Embedding](#44-fe-1--face-embedding)
    - [4.5 DI-1 — Document Forgery Detection](#45-di-1--document-forgery-detection)
-   - [4.6 Media Management](#46-media-management)
+   - [4.6 Face Indexing](#46-face-indexing)
+   - [4.7 Media Management](#47-media-management)
 5. [Visualization](#5-visualization)
 6. [Error Handling](#6-error-handling)
 7. [API Reference](#7-api-reference)
@@ -650,7 +651,89 @@ asyncio.run(detect_document())
 
 ---
 
-### 4.6 Media Management
+### 4.6 Face Indexing
+
+Index a person's photos, then find that face again later. This is separate from
+the detection models — it runs no FI-1/DF-1/AC-1 job, and uses three endpoints
+on the same host and API key:
+
+| Method | Endpoint |
+|---|---|
+| `faceEnroll(images)` | `POST /api/v1/facesim/v1/enroll` |
+| `tenants()` | `GET /api/v1/facesim/v1/subjects` |
+| `faceSearch(image, limit)` | `POST /api/v1/facesim/v1/search` |
+
+#### Enrol a face
+
+```python
+enrolled = client.faceEnroll([
+    "data_samples/face_similiar/person_1/A.jpeg",
+    "data_samples/face_similiar/person_1/B.jpeg",
+])
+
+print(enrolled["subject_id"])
+for face in enrolled["faces"]:
+    print(face["face_id"], face["status"])   # "uploaded" or "failed"
+```
+
+Accepts **1–10 images** of the same person, and only **JPEG, PNG, or WebP**.
+Every file is validated before anything is sent, so a bad path never leaves a
+half-built subject on the server.
+
+`faceEnroll` returns as soon as the photos reach S3. The embeddings are
+generated in the background, so each face comes back as `uploaded`, not
+`processed` — poll `tenants()` to see them settle. One failed upload marks only
+its own face rather than sinking the batch.
+
+#### Check indexing progress
+
+```python
+for subject in client.tenants()["subjects"]:
+    for face in subject["faces"]:
+        print(subject["subject_id"], face["name"], face["status"], face["error"])
+```
+
+| Status | Meaning |
+|---|---|
+| `pending` | Upload URL created; the object has not been acknowledged yet |
+| `uploaded` | Stored; waiting for a worker |
+| `processing` | A worker is generating the embedding |
+| `processed` | Embedding stored — the face is searchable |
+| `failed` | Upload validation or embedding failed — see `error` |
+
+Only `processed` faces are searched, so searching too early returns `count: 0`.
+
+#### Search a face
+
+```python
+matches = client.faceSearch("data_samples/face_similiar/person_1/A.jpeg", limit=10)
+
+print(matches["count"])
+for match in matches["results"]:
+    print(match["rank"], match["subject_id"], match["similarity_score"])
+```
+
+The photo is posted as `multipart/form-data` rather than Base64 in a JSON body,
+which keeps it clear of the server's 100 KiB JSON limit. `limit` is clamped to
+1–50 and defaults to 50.
+
+Search is independent of enrolment: it matches everything already indexed on the
+account, including from earlier sessions. The same subject can appear more than
+once because every enrolled face has its own embedding, and results run from
+highest similarity down.
+
+Unsupported formats are converted to JPEG when **Pillow** is installed
+(`pip install Pillow`); without it you get a clear `ValidationError` instead of
+a server-side `invalid_image`. The conversion also bakes any EXIF rotation into
+the pixels — an image left with a stale orientation tag is read sideways by face
+detection and comes back as `no_face_detected`.
+
+A full runnable script lives in
+[`examples/test_face_indexing.py`](examples/test_face_indexing.py).
+
+---
+
+### 4.7 Media Management
 
 #### Get Media
 
@@ -960,6 +1043,40 @@ Raises `ValueError` if no result artifact is found.
 
 ---
 
+#### `faceEnroll(images) -> Dict`
+
+Enrol 1–10 photos of one person: creates the subject, then uploads each image
+to its presigned S3 URL.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `images` | `list[str]` | Local paths. JPEG, PNG, or WebP only |
+
+Returns the enroll response — `subject_id`, `status`, and a `faces` array whose
+`status` is set to `uploaded` or `failed` per image. Embeddings follow out of
+band; poll `tenants()` for `processed`.
+
+Raises `ValidationError` for an empty list, more than 10 images, a missing file,
+or an unsupported image type — all checked before any request is sent.
+
+#### `tenants() -> Dict`
+
+Every subject and face on the account: `{"tenant_id", "subjects"}`, where each
+subject holds `face_id`, `name`, `status`, `embedding`, `image_url`, and `error`.
+
+#### `faceSearch(image, limit=50, timeout=120.0) -> Dict`
+
+Rank enrolled faces against a query photo, posted as `multipart/form-data`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `image` | `str` | — | Local path to the query photo |
+| `limit` | `int` | `50` | Matches to return, clamped to 1–50 |
+| `timeout` | `float` | `120.0` | Seconds — embedding takes longer than a plain request |
+
+Returns `{"tenant_id", "count", "results"}` with results ordered from highest
+similarity down. Only faces with `status: "processed"` are searched.
+
 #### `get_media(jobid) -> Dict`
 
 `GET /api/v1/jobs/{jobid}` — fetch the current state of a media record.

{authentasdk-0.2.8 → authentasdk-0.2.9}/src/authentasdk.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/authenta/__init__.py
 src/authenta/async_authenta_client.py
 src/authenta/authenta_client.py
 src/authenta/authenta_exceptions.py
+src/authenta/face_auth.py
 src/authenta/visualization.py
 src/authentasdk.egg-info/PKG-INFO
 src/authentasdk.egg-info/SOURCES.txt