Python SDK Quickstart

Hosted service offline

The hosted AEGIS API is offline (September 2026). Every client.evaluate() call, sandbox mode included, is a call to it, so the SDK raises an AegisError subclass instead of returning a decision (aegis-governance 1.4.2 adds ServiceUnavailableError and puts the status URL in the message; 1.4.1 raises ServerError or ConnectionError without it). The examples below show the interface. Status: undercurrentholdings.com/status.

Prerequisites

Install the AEGIS Python SDK from PyPI:

pip install aegis-governance

API keys were issued at portal.undercurrentholdings.com; a key does not restore evaluation while the hosted service is offline.

Alternatively, use the REST API Quickstart for direct HTTP integration without installing a package.

Basic Evaluation

from aegis import Aegis

client = Aegis(api_key="uk_live_xxx")  # or set AEGIS_API_KEY env var

decision = client.evaluate(
    proposal_summary="Add Redis caching layer to reduce API latency",
    estimated_impact="medium",
    risk_baseline=0.02,
    risk_proposed=0.05,
    novelty_score=0.75,
    complexity_score=0.8,
    quality_score=0.9,
)

print(decision.status)       # "proceed" | "pause" | "halt" | "escalate"
print(decision.confidence)   # 0.87
print(decision.rationale)    # "All 6 gates passed. Proposal approved."

Quick Risk Check

API key required

risk_check() has no sandbox path — it always calls the authenticated /risk-check endpoint. A keyless Aegis() client raises AuthenticationError.

For simple threshold-based checks without the full gate pipeline:

result = client.risk_check(
    risk_score=0.15,
    threshold=0.3,
    action_description="Deploy to production",
)
print(result.safe)  # True

Async Usage

from aegis import AsyncAegis

async with AsyncAegis() as client:
    decision = await client.evaluate(
        proposal_summary="Migrate database to Postgres 17",
        estimated_impact="high",
    )

Gate Results

Access individual gate evaluations:

decision = client.evaluate(proposal_summary="...")

if decision.gates:
    print(decision.gates.risk)        # GateResult(passed=True, value=0.05, ...)
    print(decision.gates.novelty)     # GateResult(passed=True, value=0.75, ...)
    print(decision.gates.complexity)  # GateResult(passed=True, value=0.80, ...)

Error Handling

import aegis

try:
    decision = client.evaluate(proposal_summary="...")
except aegis.ServiceUnavailableError as e:  # HTTP 503 or no connection (1.4.2+)
    print(e.message)  # ends with "See https://undercurrentholdings.com/status/"
except aegis.SandboxLimitError as e:        # keyless 429
    print(e.message)
except aegis.AuthenticationError:
    print("Invalid API key")
except aegis.RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except aegis.ValidationError as e:
    print(f"Bad request: {e.message}")
except aegis.AegisError as e:
    print(f"API error: {e.message} (request_id={e.request_id})")

Configuration

client = Aegis(
    api_key="uk_live_xxx",       # or AEGIS_API_KEY env var
    base_url="https://...",      # or AEGIS_BASE_URL env var
    timeout=60.0,                # seconds (default: 30)
    max_retries=3,               # retry attempts (default: 2)
)

Customer Management

profile = client.get_profile()
print(profile.tier)              # "professional"

usage = client.get_usage()
print(usage.total_evaluations)   # 847

keys = client.list_keys()
new_key = client.create_key("CI Pipeline")

Next Steps

REST API Quickstart — direct HTTP integration
MCP Tools — AI agent integration
Customer Onboarding — rate limits, tiers, and billing
Parameter Reference — full parameter documentation

Python SDK Quickstart

On this page