aegis-platform-sdk (Python)

Typed Python client + functional namespace for the AEGIS platform — IAM, OSDK applications, ontology surface, LLM inference, RAG. Maps 1:1 to the HTTPS API.

• Distribution: pip install aegis-platform-sdk
• Import: from aegis import …
• Repo: https://github.com/Safe-Core/aegis-python-sdk (private)
• CI / release: see PUBLISHING.md

The package name on disk is aegis (the legacy aegis_sdk shim is deprecated and removed in v0.3).

Install

pip install aegis-platform-sdk
# or, from source while developing AEGIS:
pip install -e ./aegis-python-sdk

Two ways to use

Client style — explicit auth, structured access

from aegis import AegisClient

# Issue an OSDK token in the AEGIS UI: Governance → OSDK Applications.
client = AegisClient(
    base_url="https://aegis.example.com",
    token="osdk_xK9pQzR2L8mYvN4w...",
)

me = client.auth.me()
print(me.username, me.permissions)        # → osdk:my-app, ["ontology.types.read", ...]

users = client.iam.users.list()
for u in users:
    print(u.username, u.roles)

nav = client.iam.nav.tree()
for s in nav.sections:
    print(s.id, "·", len(s.items), "items")

The OSDK token is shown once on creation. Treat it like a database credential — rotate, never commit.

Functional style — Palantir-like namespace

from aegis import inference

# Auto-uses a default client built from AEGIS_API_URL / AEGIS_TOKEN env vars.
out = inference.complete("Summarise the latest threat indicators")
print(out["response_text"])

answer = inference.chat(
    messages=[{"role": "user", "content": "What intel exists on elections?"}],
    rag_sources=["telegram", "tiktok_comments"],
)

models = inference.models()
collections = inference.collections()

Pin a pre-authed client globally:

import aegis
client = aegis.AegisClient(token="osdk_…")
aegis.set_default_client(client)

# Now every aegis.inference.* call uses the bearer.
aegis.inference.complete("hi")

Or pass it per-call:

aegis.inference.complete("hi", client=my_client)

Quick start — human auth (login)

from aegis import AegisClient

client = AegisClient(base_url="https://aegis.example.com")
pair = client.auth.login(username="alice", password="…", totp_code="123456")
# JWT is now attached to the client; refresh handled by client.auth.refresh(...).

me = client.auth.me()
client.auth.change_password("…", "new-strong-pass-12+chars")
client.auth.logout(pair.refresh_token)

Surface

Write surfaces (PUT / PATCH / DELETE for users, roles, etc.) are on the short-term roadmap — open an issue if you need them sooner.

Errors

from aegis import AegisClient, PermissionDeniedError, AuthError

try:
    client.iam.users.list()
except PermissionDeniedError as exc:
    print(f"missing perm: {exc.detail}")
except AuthError as exc:
    print(f"token expired or invalid: {exc.detail}")

Hierarchy: AegisAPIError ← AuthError (401) · PermissionDeniedError (403) · NotFoundError (404).

Environment overrides

Development

cd aegis-python-sdk
pip install -e ".[dev]"
pytest -v

The unit suite uses respx to stub the HTTPS surface — no live stack needed. The integration suite (under tests/integration/) runs against a real ontology-module API at $AEGIS_API_URL and is skipped if the service is unreachable.