AEGIS Python SDK

Status: the hosted AEGIS service was taken offline in September 2026. Evaluation is always a call to that service, so evaluate() does not succeed: it raises an aegis.AegisError subclass (for HTTP 429, 5xx, connection failure, and timeout, the message ends with See https://undercurrentholdings.com/status/), and the MCP evaluation tool returns that error as JSON. Nothing in this package evaluates a proposal locally: sandbox mode is also a server call. Product status: https://undercurrentholdings.com/status/.

What this package contains

• Aegis — a synchronous client for the AEGIS REST API (evaluate, risk_check, health, customer and decision endpoints, attestations).
• AsyncAegis — the same surface on httpx.AsyncClient.
• aegis-mcp-server — a local stdio MCP server (with the [mcp] extra) that wraps the client. tools/list returns six tools: aegis_evaluate_proposal, aegis_quick_risk_check, aegis_health, aegis_list_decisions, aegis_get_decision, aegis_get_usage. Without an API key, aegis_evaluate_proposal and aegis_health call the API and the other four return an authentication error without calling it.
• verify_attestation_locally — an offline verifier for AEGIS attestation envelopes (with the [verify] extra). It makes no network call.

Install

pip install aegis-governance            # client + async client
pip install "aegis-governance[mcp]"     # adds the local MCP server
pip install "aegis-governance[verify]"  # adds the offline attestation verifier

What a call does today

import aegis

client = aegis.Aegis()  # no key: sandbox mode, which calls the hosted service

try:
    decision = client.evaluate(proposal_summary="Add Redis caching layer")
except aegis.ServiceUnavailableError as e:  # HTTP 503 or no connection
    print(e.message)  # "... See https://undercurrentholdings.com/status/"
except aegis.AegisError as e:               # 429, other 5xx, timeout, ...
    print(e.message)

Errors raised by evaluate() (keyed or sandbox) for HTTP 429, 5xx, connection failure, and timeout end with the status URL. ServiceUnavailableError (new in 1.4.2) is raised for 503 and for connection failure. Each instance is also the class 1.4.1 raised for the same cause: a 503 is also a ServerError (status_code == 503), and a connection failure is also a ConnectionError (status_code is None), so except ServerError / except ConnectionError handlers route as before. Two cases that 1.4.1 let escape as non-AegisError exceptions now raise AegisError subclasses: a connection reset or a server that closes without replying (was a raw httpx exception), and a redirect or non-JSON reply (was a raw JSONDecodeError).

Error classes

All are exported from aegis and subclass aegis.AegisError.

Pass idempotency_key="..." to evaluate() (keyed mode) for cross-process deduplication; sandbox mode does not send one.

Local MCP server

The server runs on your machine over stdio. It is a thin client of the hosted service, so its evaluation tools return the same status error.

Claude Code:

claude mcp add aegis -- aegis-mcp-server

Cursor / Windsurf (.cursor/mcp.json):

{
  "mcpServers": {
    "aegis": { "command": "aegis-mcp-server" }
  }
}

Offline attestation verification

verify_attestation_locally checks an in-toto Statement v1 / DSSE v1 envelope signed with hybrid Ed25519 + ML-DSA-65 (design record ADR-011) against public keys you supply. It needs no server.

from aegis import AttestationVerifyKey, verify_attestation_locally

keys = AttestationVerifyKey(
    ed25519_public=b"...32 bytes raw...",
    mldsa65_public=b"...1952 bytes raw...",
)
valid, error_class = verify_attestation_locally(
    envelope=envelope,
    expected_digest="<sha256 lowercase hex 64>",
    expected_environment="production",  # "production" | "staging" | "preview"
    keys=keys,
)

It returns the same error_class strings as the server's POST /attestations/verify (for example AttestationDigestMismatch, AttestationExpired, AttestationMLDSAVerifyFailed). Issuing a new attestation needs the hosted service; verifying one does not.

Reading the source

The source ships with the package. The sdist on PyPI (aegis_governance-<version>.tar.gz, "Download files" on the project page) contains src/aegis/ and tests/; an installed copy is under site-packages/aegis/.

• src/aegis/_client.py, _async_client.py — the clients. evaluate() sends the proposal to /evaluate (keyed) or /sandbox/evaluate (no key).
• src/aegis/_http.py — transport: TLS, retries on 429 with Retry-After and on 500/502/503/504, idempotency keys, error mapping.
• src/aegis/_errors.py — the error classes and the status-URL note.
• src/aegis/_mcp.py — the local MCP server and its six tools.
• src/aegis/_verify_local.py — the offline verifier.
• tests/ — the test suite (in the unpacked sdist: pip install -e ".[dev,verify]" && pytest).

The changelog is CHANGELOG.md.

License

Apache 2.0 - see LICENSE for details.