Metadata-Version: 2.1
Name: aeglis
Version: 1.0.2
Summary: Official Python SDK for the Aeglis Security API
Home-page: https://developer.aeglis.com
Author: Aeglis Systems
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.1

# Aeglis Python SDK

The official Python SDK for Aeglis — The Hybrid AI Security Engine. Protect your application backend from zero-day phishing, malicious payloads, and embedded macro-viruses in real-time. Built specifically for high-throughput enterprise environments, FinTech APIs, and data science infrastructure.

## Installation

Install the package from PyPI using pip:

```bash
pip install aeglis

```

## Quick Start

Retrieve your API Key and Webhook Secret from the Aeglis Developer Dashboard.

```python
from aeglis import Aeglis

# Initialize the secure client instance
client = Aeglis(api_key="sk_live_YourApiKeyHere")

```

---

## Core API Methods

### 1. Quick Scan (Synchronous)

Best for evaluation of short text inputs, chat moderation, and processing outbound marketing links.

```python
try:
    response = client.scan(
        input_text="Claim your free reward at [http://suspicious-link.com](http://suspicious-link.com)",
        end_user_id="user_id_9982"  # Optional internal tracking reference
    )
    
    print(response["status"]) # "success"
    print(response["data"]["risk_level"]) # "DANGER", "WARNING", or "SAFE"
except Exception as e:
    print(f"Scanning failed: {e}")

```

### 2. Deep File Scan (Asynchronous)

Best for user document uploads, KYC verification pipelines, and large file extraction (up to 50MB).
*Note: This operations fires a background worker thread. The final granular security report will be pushed to your configured Webhook endpoint.*

```python
try:
    response = client.deep_scan(
        file_path="./uploads/user_resume.pdf",
        input_text="Contextual document upload for review", # Optional
        end_user_id="document_ref_5548" # Optional reference mapped back in webhook
    )
    
    print(response["status"]) # "processing"
    print(response["message"]) # "File accepted. Result will be dispatched to your Webhook."
except Exception as e:
    print(f"Deep scan upload failed: {e}")

```

---

## Webhook Verification (Security)

Aeglis dispatches scanning outputs asynchronously via HTTP POST. To maintain integrity and avoid payload interception or spoofing, you must verify the inbound cryptographic HMAC SHA-256 signature.

The SDK compresses this validation execution into a single method.

⚠️ **CRITICAL INTEGRATION NOTICE:** Signature verification strictly requires the **raw, unparsed request body bytes**. If your framework maps incoming streams directly into a parsed dictionary, cryptographic calculation will mismatch due to whitespace normalization.

### FastAPI Production Implementation Example:

```python
from fastapi import FastAPI, Request, HTTPException
from aeglis import Aeglis, AeglisError

app = FastAPI()
client = Aeglis(api_key="sk_live_YourApiKeyHere")

WEBHOOK_SECRET = "whsec_YourDashboardSecretHere"

@app.post("/v3/aeglis-callback")
async def handle_security_webhook(request: Request):
    # 1. Capture the raw unparsed request body bytes
    raw_payload = await request.body()
    
    # 2. Extract the signature header
    signature_header = request.headers.get("x-aeglis-signature")
    
    try:
        # 3. Securely verify signature using timing attack protections
        verified_event = client.verify_webhook(
            raw_payload=raw_payload,
            signature_header=signature_header,
            webhook_secret=WEBHOOK_SECRET
        )
        
        # Extract metadata and routing flags from the nested data payload
        event_data = verified_event.get("data", {})
        entity_reference = event_data.get("user_id") # Returns "document_reference_ref_5548"
        risk_level = event_data.get("risk_level")
        
        if risk_level == "DANGER":
            # Execute internal system quarantine logic using the reference
            pass
            
        return {"status": "processed"}
        
    except AeglisError as e:
        # Prevent tracking parameter leakage on failure responses
        raise HTTPException(status_code=400, detail="Invalid signature verification failed.")

```

---

## Exception Handling

The SDK exposes granular API errors via custom exceptions. Use standard Python try-except blocks to catch runtime anomalies cleanly.

```python
from aeglis import Aeglis, AeglisError

client = Aeglis(api_key="sk_live_YourApiKeyHere")

try:
    client.scan(input_text="") # Empty string payload violation
except ValueError as e:
    print(f"Validation Error: {e}")
except AeglisError as e:
    print(f"API Error Boundary Hit: {e}")

```

## Resources

* [Official Documentation Portal](https://docs.aeglis.com)
* [Developer Settings Portal](https://developer.aeglis.com)

