Metadata-Version: 2.4
Name: averian-ai-validator-sdk
Version: 1.0.1214
Summary: Averian AI Validator SDK
License: MIT
Project-URL: Homepage, https://averian.io
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests

# Averian AI Validator SDK User Guide

Welcome to the Averian AI Validator Python SDK. This guide provides a comprehensive overview of how to integrate automated anomaly detection into your workflows.

---

## 1. Introduction
The SDK allows you to interact with the Averian AI Validator platform programmatically. You can manage projects, upload training data, trigger model retraining, and most importantly, run real-time inference to detect anomalies in images.

## 2. Setup

### Installation
The SDK is available via pip:
```bash
pip install averian-ai-validator-sdk
```

### Authentication
Authentication is handled via **API Keys**. 
*   **API Keys** are generated in the "Organization Settings" page of the web platform.
*   Each API Key is bound to a specific **Organization**.
*   The key carries specific permissions (Inference, Admin, etc.). Ensure your key has `Inference` permissions for production use.

---

## 3. Core Concepts

> **Note on Configuration**: While this SDK provides methods to create and configure projects, input sources, and processors, it is **highly recommended** to use the **AI Validator webapp** for initial setup. The webapp provides essential visual tools for defining regions of interest, masking, and processor sequencing that are difficult to replicate via code.

*   **Organization**: Your top-level container. An API key gives you access to one organization.
*   **Project**: A specific use-case or product line (e.g., "PCBA Inspection").
*   **Input Source**: A specific camera, station, or data stream within a project.
*   **Model Ensemble**: A trained AI model hosted on the platform. Each Input Source typically has a "Default Ensemble" used for inference.

---

## 4. Basic Workflow

### Connecting
```python
from averian_ai_validator_sdk import APIClient

api = APIClient()
# Note: api_host is the base URL of your instance (e.g., https://validator.yourcompany.com)
api.connect("https://validator_address", "YOUR_API_KEY")
```

### Navigating Projects and Sources
To run inference, you need a `project_id` and an `input_id`.

```python
# List all projects in your organization
projects = api.get_projects()['projects']
for p in projects:
    print(f"Project: {p['name']} (ID: {p['id']})")

# List input sources for a specific project
project_id = "your-project-uuid"
sources = api.get_input_sources(project_id)
for s in sources:
    print(f"Source: {s['name']} (ID: {s['id']})")
```

### Running Inference
Inference requires an image (as a blob), the project ID, input ID, and a model ID.

```python
project_id = "..."
input_id = "..."
image_path = "sample.jpg"

# 1. Get the model (using the default ensemble for the source)
source = api.get_input_source_by_id(project_id, input_id)
model_id = source.get('defaultEnsemble')

# 2. Prepare the image
img_blob = api.read_file_as_blob(image_path)

# 3. Run Inference
result = api.infer(
    project_id=project_id, 
    input_id=input_id, 
    model_id=model_id, 
    img_name="sample", 
    img_ext="jpg", 
    img_blob=img_blob
)

print(f"Is Anomalous: {result['isAnomalous']}")
```

### Retrieving Heatmaps
If an anomaly is detected, you can download a visual heatmap showing the localized area of concern.

```python
heatmap_bytes = api.fetch_result_image_with_heatmap(project_id, result['id'])
with open("result_heatmap.jpg", "wb") as f:
    f.write(heatmap_bytes)
```

---

## 5. Advanced Usage

### Data Management
You can programmatically manage your training and testing datasets.
*   `move_from_train_to_test(project_id, image_id)`
*   `set_image_anomality(project_id, image_id, is_anomaly, coordinates)`: Re-label data from the SDK.

### Retraining
Trigger a new training session for a specific input source:
```python
from averian_ai_validator_sdk import ModelType
api.train_new_model(project_id, input_id, ModelType.PATCHCORE)
```


### Step 6 — Clean Up (Optional)

```python
api.del_result(project_id, result['id'])
```

---

For the full API reference, visit the Averian AI Validator documentation.
