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:

pip install aeglis

Quick Start

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

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.

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.

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:

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.

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
• Developer Settings Portal