Metadata-Version: 2.4
Name: authenta
Version: 0.1.1
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
Author-email: rrarjunadhithya@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20.0

# Authenta SDK Documentation

Welcome to the official documentation for the **Authenta Python SDK**. This library allows you to integrate state-of-the-art deepfake and manipulated media detection into your Python applications.

---

## 1. Getting Started

### Installation

You can install the SDK via `pip` for production use or install from source for local development.

**Option A: Install from PyPI (Recommended)**
```bash
pip install authenta
```

**Option B: Local Development**
If you want to modify the SDK source code:
```bash
git clone https://github.com/phospheneai/authenta-python-sdk.git
cd authenta-python-sdk
pip install -e .
```

### Authentication & Initialization

To use the SDK, you must initialize the `AuthentaClient` with your API credentials.

```python
from authenta import AuthentaClient

client = AuthentaClient(
    base_url="https://platform.authenta.ai",
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)
```

---

## 2. Models & Capabilities

Authenta provides specialized models for different media types. You select the model using the `model_type` parameter in SDK methods.

| Model Type | Modality | Capability |
| :--- | :--- | :--- |
| **`AC-1`** | Image | **AI-Generated Image Detection:** Identifies images created by Generative AI (e.g., Midjourney, Stable Diffusion) or manipulated via editing tools. |
| **`DF-1`** | Video | **Deepfake Video Detection:** Detects face swaps, reenactments, and other facial manipulations in video content. |

---

## 3. Workflows

### Quick Detection (Synchronous)
Use the `.process()` method to handle uploading and waiting for results in a single blocking call. This is ideal for scripts or simple integrations.

```python
# Example: Detect AI-generated image
media = client.process("samples/nano_img.png", model_type="AC-1")

print(f"Media ID: {media['mid']}")
print(f"Status: {media['status']}")
print(f"Is Fake?: {media.get('fake')}")
```

### Async Upload & Polling
For non-blocking workflows (e.g., web servers), use a two-step process: upload first, then poll for status using the Media ID (`mid`).

```python
# 1. Initiate Upload
upload_meta = client.upload_file("samples/video.mp4", model_type="DF-1")
mid = upload_meta["mid"]
print(f"Upload started. Media ID: {mid}")

# ... perform other tasks ...

# 2. Check Status Later
final_media = client.wait_for_media(mid)
if final_media["status"] == "PROCESSED":
    print(f"Result: {final_media.get('fake')}")
```

### Visualizing Results
The SDK includes a `visualization` module to generate visual overlays (heatmaps and bounding boxes) to help you interpret detection results.

**1. Heatmaps (Images & Video)**
Generate a visual heatmap indicating manipulated regions.
```python

from authenta.visualization import save_heatmap
media = client.process("data_samples/nano_img2.png", model_type="AC-1")
# simply pass the media and output dir 
save_heatmap(
    media=media,
    out_path="results/image_heatmap.jpg",
    model_type="AC-1",
)

```
Generate an activation heatmap  indicating manipulated regions for faceswap detection .
```python
from authenta.visualization import *
media = client.process("data_samples/test_00000121.mp4", model_type="DF-1")
save_heatmap(
    media,
    out_path="results/deepfake_heatmap.mp4",
    model_type="DF-1",
)
```

**2. Bounding Box Video (DF-1 Only)**
Draw detection boxes around faces in a deepfake video.
```python
from authenta.visualization import *

media = client.process("data_samples/test_00000121.mp4", model_type="DF-1")

save_bounding_box_video(
    media,
    src_video_path="data_samples/test_00000121.mp4",
    out_video_path="results/analyzed_video.mp4",
)

```


---

## 4. API Reference

### Class: `AuthentaClient`

#### `__init__(base_url, client_id, client_secret)`
Initializes the client session.

#### `process(path: str, model_type: str, interval: float = 5.0, timeout: float = 600.0) -> Dict`
A high-level wrapper that combines upload and polling.
* **Returns:** A dictionary containing the final processed media state.
* **Raises:** `TimeoutError` if processing exceeds `timeout`.

#### `upload_file(path: str, model_type: str) -> Dict`
Uploads a file to the Authenta platform.
* **path:** Local path to the image or video file.
* **model_type:** `AC-1` (Image) or `DF-1` (Video).
* **Returns:** Dictionary with initial metadata (including `mid`).

#### `wait_for_media(mid: str, interval: float = 5.0, timeout: float = 600.0) -> Dict`
Blocks execution until the media status becomes `PROCESSED` or `FAILED`.
* **mid:** The Media ID returned from `upload_file`.

#### `get_media(mid: str) -> Dict`
Retrieves the current status and details of a specific media record.

#### `list_media(**params) -> Dict`
Lists historical media records.
* **params:** Query parameters like `page`, `pageSize`.

#### `delete_media(mid: str) -> None`
Permanently removes a media record and its associated data from the platform.
