Python SDK

Official Python SDK for ATHENA Trust Calibration Platform.

Installation

pip install athena-sdk

Optional: Async Support with HTTP/2

pip install athena-sdk[async]

Quick Start

from athena import Athena

athena = Athena(api_key="ak_xxx")
result = athena.bias.detect(
    user_id="user_123",
    action_taken="approved",
    ai_recommended="approved"
)
print(f"Bias: {result.bias_detected}, Risk: {result.risk_level}")

Features

• ✅ Sync + Async - Both Athena and AsyncAthena clients

• ✅ Type Safety - Full Pydantic v2 models with validation

• ✅ Auto-Retry - Exponential backoff with rate limit handling

• ✅ Webhook Verification - HMAC-SHA256 signature validation

• ✅ Framework Support - Flask, FastAPI, Django decorators

• ✅ Zero Config - Works out of the box with sensible defaults

Configuration

from athena import Athena

athena = Athena(
    api_key="ak_prod_...",        # Required
    base_url="https://...",       # Optional (custom base URL)
    timeout=30,                   # Optional (request timeout in seconds)
    max_retries=3                 # Optional (retry count)
)

API Reference

Bias Detection

result = athena.bias.detect(
    user_id="doctor_456",
    action_taken="approved",
    ai_recommended="approved",
    time_to_decision_ms=2000,
    evidence_reviewed=["lab_results", "patient_history"]
)

if result.bias_detected:
    print(f"⚠️  Bias types: {[b.type for b in result.bias_types]}")
    print(f"Risk level: {result.risk_level}")
    print(f"Recommendation: {result.recommendation}")

Trust Calibration

calibration = athena.calibrate.analyze(
    user_id="user_123",
    domain="healthcare",
    time_window_days=30
)

print(f"Calibration: {calibration.calibration}")
print(f"AI Accuracy: {calibration.metrics.ai_accuracy:.2%}")
print(f"Follow Rate: {calibration.metrics.follow_rate:.2%}")

Trust Score

score = athena.trust_score.calculate(
    customer_id="org_123",
    user_id="user_456",
    domain="finance",
    time_window_days=30
)

print(f"Trust Score: {score.trust_score_pct:.1f}%")
print(f"Calibration: {score.calibration}")
print(f"Recommendations: {score.recommendations}")

Audit Trail

audit = athena.audit.list(
    customer_id="org_123",
    user_id="user_456",
    limit=50,
    offset=0
)

for entry in audit.entries:
    print(f"{entry.timestamp}: {entry.decision} (Calibration: {entry.calibration})")

Webhooks

webhook = athena.webhooks.create(
    url="https://your-app.com/webhook",
    events=["bias.detected", "trust.drop"]
)

# ⚠️  SAVE THIS SECRET - only shown once!
print(f"Webhook ID: {webhook.id}")
print(f"Secret: {webhook.secret}")

Compliance Exports

pdf_bytes = athena.export.generate(
    customer_id="org_123",
    template="eu-ai-act",
    format="pdf",
    start_date="2025-01-01",
    end_date="2025-12-31"
)

with open("eu-ai-act-report.pdf", "wb") as f:
    f.write(pdf_bytes)

Async Client

For high-performance applications:

from athena import AsyncAthena
import asyncio

async def main():
    async with AsyncAthena(api_key="ak_xxx") as athena:
        result = await athena.bias.detect(
            user_id="user_123",
            action_taken="approved",
            ai_recommended="approved"
        )
        print(f"Bias detected: {result.bias_detected}")

asyncio.run(main())

Webhook Verification

Flask

from flask import Flask, request
from athena.utils.flask_webhook import athena_webhook
import os

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
@athena_webhook(secret=os.environ["WEBHOOK_SECRET"])
def handle_webhook():
    data = request.get_json()
    print(f"Received: {data['type']}")
    
    if data['type'] == 'bias.detected':
        # Alert your team
        pass
    elif data['type'] == 'trust.drop':
        # Trigger retraining
        pass
    
    return {"status": "ok"}

FastAPI

from fastapi import FastAPI, Request
from athena.utils.fastapi_webhook import verify_athena_webhook
import os

app = FastAPI()
WEBHOOK_SECRET = os.environ["WEBHOOK_SECRET"]

@app.post("/webhook")
async def handle_webhook(request: Request):
    payload = await verify_athena_webhook(request, WEBHOOK_SECRET)
    print(f"Received: {payload['type']}")
    return {"status": "ok"}

Manual Verification

from athena.utils import verify_webhook_signature

def handle_webhook(request):
    try:
        verify_webhook_signature(
            payload=request.body.decode(),
            signature_header=request.headers["X-Athena-Signature"],
            secret=WEBHOOK_SECRET,
            tolerance=300  # 5 minutes
        )
    except ValidationError:
        return {"error": "Invalid signature"}, 401
    
    # Process webhook...

Available Resources

Resource	Methods	Description
athena.calibrate	analyze(), get_status()	Trust calibration analysis
athena.bias	detect(), is_present()	Cognitive bias detection
athena.trust_score	calculate(), trend()	Trust score calculation
athena.audit	list()	Audit trail access
athena.webhooks	create(), list(), update(), delete()	Webhook management
athena.export	generate(), get_templates()	Compliance reports
athena.stats	get()	Aggregated metrics
athena.users	at_risk()	At-risk user detection
athena.engines	status(), benchmarks()	System status & performance

Error Handling

from athena import Athena, AuthenticationError, RateLimitError, ValidationError

athena = Athena(api_key="ak_xxx")

try:
    result = athena.bias.detect(...)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ValidationError as e:
    print(f"Invalid request: {e.message}")
except Exception as e:
    print(f"Unexpected error: {e}")

Support

• 📚 Full API Reference

• 🐛 GitHub Issues

• 📧 [email protected]

License

MIT © ATHENA