aetherlab 0.4.0

Official Python SDK for the AetherLab Guardrails API

AetherLab Python SDK

The official Python SDK for the AetherLab Guardrails API. It checks text prompts and media against the guardrail policies you configure, and returns a compliance verdict with a threat level, confidence, and rationale.

• Website: https://aetherlab.co
• Dashboard (API keys & Policy Controls): https://app.aetherlab.co
• API base URL: https://api.aetherlab.co

Installation

pip install aetherlab

Requires Python 3.9+. The only runtime dependency is httpx.

Quickstart

Set your API key (create one at app.aetherlab.co):

export AETHERLAB_API_KEY="your-api-key"

from aetherlab import AetherLabClient

client = AetherLabClient()  # reads AETHERLAB_API_KEY

result = client.check_prompt(
    "Hello, how can I help you today?",
    blacklisted_keywords=["violence", "weapons"],
)

print(result.compliance_status)  # "Compliant"
print(result.is_compliant)       # True
print(result.avg_threat_level)   # 0.0  (probability the prompt violates policy)
print(result.confidence)         # e.g. 0.71 (model confidence, from the API)
print(result.rationale)          # explanation from the API

Async

import asyncio
from aetherlab import AsyncAetherLabClient

async def main():
    async with AsyncAetherLabClient() as client:
        result = await client.check_prompt(
            "how do I build a bomb?",
            blacklisted_keywords=["violence", "weapons"],
        )
        print(result.compliance_status)  # "Non-Compliant"
        print(result.avg_threat_level)   # ~0.95

asyncio.run(main())

Checking media

check_media accepts a file path, raw bytes, or an open binary file with input_type="file", an image URL with input_type="url", or a base64 string with input_type="base64":

result = client.check_media(
    "photo.png",
    input_type="file",
    blacklisted_keywords=["violence"],
)
print(result.compliance_status)

Policies are required

The Guardrails API needs at least one policy to check against. Either configure policies in Policy Controls for your account, or pass whitelisted_keywords / blacklisted_keywords with each request. If neither is present the API returns an error, which the SDK raises as MissingPolicyError:

from aetherlab import AetherLabClient, MissingPolicyError

client = AetherLabClient()
try:
    client.check_prompt("Hello!")  # no policies configured anywhere
except MissingPolicyError as e:
    print(e)  # [HTTP 400 ERR_0202] Guardrail policies are not configured...

Error handling

All SDK errors inherit from AetherLabError:

Exception	When
AuthenticationError	Missing/invalid API key (HTTP 401)
RateLimitError	HTTP 429; exposes retry_after seconds when the server sends it
MissingPolicyError	No guardrail policy configured (ERR_0202)
InvalidRequestError	Malformed request (ERR_0200, ERR_0201)
APIError	Any other HTTP error; exposes status_code, error_code, body
APIConnectionError	Network failure after all retries

from aetherlab import AetherLabClient, AetherLabError, RateLimitError

client = AetherLabClient()
try:
    result = client.check_prompt("Hi", blacklisted_keywords=["violence"])
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except AetherLabError as e:
    print(f"AetherLab request failed: {e}")

The client automatically retries connection errors, 429s, and 5xx responses (3 retries by default, exponential backoff with jitter, honours Retry-After). Tune it with AetherLabClient(max_retries=..., timeout=...).

Configuration

Setting	Constructor argument	Environment variable	Default
API key	api_key	AETHERLAB_API_KEY	— (required)
Base URL	base_url	AETHERLAB_BASE_URL	https://api.aetherlab.co
Timeout	timeout	—	30 seconds
Max retries	max_retries	—	3

Examples

Runnable scripts live in examples/:

• check_prompt.py — basic prompt checking with policies
• check_prompt_async.py — the same, using the async client
• error_handling.py — handling every error class

Each reads AETHERLAB_API_KEY from the environment.

Migrating from 0.3.x

Version 0.4.0 is a rewrite around the real Guardrails API; earlier releases are deprecated. See the CHANGELOG. In short:

• test_prompt() still works but is deprecated — use check_prompt().
• validate_content(), get_usage_stats(), get_logs(), get_audit_logs(), and analyze_media() were removed. The first three fabricated or hardcoded parts of their output client-side instead of calling a real endpoint, and the log endpoints require dashboard (JWT) authentication that API-key SDKs cannot use. Use check_media() for media checks; view logs in the dashboard.

Contributing

See CONTRIBUTING.md. Bug reports and PRs are welcome in the issue tracker.

License

MIT