A Python SDK that enforces policy at the AI invocation boundary. Every model call is validated, every violation is blocked, and every outcome — pass or fail — leaves a tamper-evident audit artifact. Governance is runtime enforcement, not documentation and not prompting.
aegis-ai-governance public beta — invocation and workflow
governance, GovernanceSession, and the aegis workflow CLI.
The package and live demo are released from main.
AEGIS sits at the invocation boundary between the host application and the model provider. Ownership is explicit and non-negotiable: the host orchestrates and calls the model; AEGIS governs and audits every invocation attempt.
AEGIS does not own orchestration, transport, retries, credentials, business state, tool execution, or provider SDK usage. It is not a hosted orchestrator, model-serving platform, queue runner, transport layer, credential broker, or remote session manager.
If a model call cannot be justified by policy and evidenced by an audit record, AEGIS treats it as invalid. That is the entire surface.
enforce_invocation() or AEGIS.enforce() — runs the complete gate
sequence in one call. Input and output are provided together. Simple integration path for non-latency-sensitive cases.
enforce_pre_call() authorizes before token spend.
enforce_post_call() validates output after the model responds.
The host model call lives between the two phases. Split mode is the @governed default since v0.3.3.
Every invocation traverses a fixed, ordered gate sequence. No step is skipped. A violation at any gate is fail-closed — the invocation is rejected and a FAIL artifact is emitted.
load_policy()pre_authorizationevaluate_guards()validate_role()validate_preconditions()validate_tool_constraints()post_authorizationpre_outputvalidate_schema()validate_postconditions()post_outputcompute_risk_score()generate_audit_artifact()from aegis import enforce_invocation # Assemble the invocation. AEGIS validates; # the host owns the model call. artifact = enforce_invocation({ "policy_file": "policies/base_policy.yaml", "model_provider": "anthropic", "model_identifier": "claude-sonnet-4-6", "role": "assistant", "input": {"query": "Summarize this incident"}, "output": {"result": "...", "confidence": 0.94}, "context": { "role_declared": True, "schema_exists": True, }, }) # artifact.verdict → "PASS" or "FAIL" assert artifact.verdict == "PASS"
from aegis import AEGIS, JsonFileAuditSink engine = AEGIS( sink=JsonFileAuditSink("audit.jsonl") ) artifact = engine.enforce(invocation)
Policies are YAML validated against
schemas/policy_dsl.schema.json (Draft-07).
Key fields: policy_version, roles,
pre_conditions, post_conditions,
output_schema, tools, guards,
risk, composition_strategy.
Split enforcement separates the authorization pass from output validation,
letting hosts block invalid requests before any tokens are consumed.
Since v0.3.3 this is the @governed default.
from aegis import enforce_pre_call, enforce_post_call # Phase A — runs before token spend pre = enforce_pre_call({ "policy_file": "policies/base.yaml", "model_provider": "anthropic", "model_identifier":"claude-sonnet-4-6", "role": "assistant", "input": {"query": "Summarize incident"}, "context": {"role_declared": True}, }) # pre.authorized → True/False # Host owns the model call output = model.generate(pre) # Phase B — validates output artifact = enforce_post_call(pre, output)
from aegis import governed # pre_call_enforcement=True is now the default # since v0.3.3. Phase A runs before the function body. @governed( policy_file="policies/base.yaml", role="assistant", model_provider="anthropic", model_identifier="claude-sonnet-4-6", ) def run_model(input_data, context): return model.generate(input_data)
The v0.9.0 beta adds session-scoped governance over multi-step AI workflows.
AEGIS.open_session() returns a GovernanceSession
context manager that enforces deterministic lifecycle state and produces correlated workflow artifacts.
from aegis import AEGIS # No module-level open_session(). # Always instance-scoped. engine = AEGIS() with engine.open_session( workflow_id="incident-review", policy_file="governance/policy.yaml", ) as session: # Step 1 — pre-call authorization pre = session.enforce_pre_call({ "role": "assistant", "input": {"query": "Summarize"}, }) # Host owns the model call output = model.generate(...) # Step 1 — post-call validation pre.complete(output) # Step 2 ... # Clean exit → COMPLETED workflow artifact # Exception exit → FAILED + re-raise
minimal, standard, regulated-high-assurance —
generated by aegis workflow init --profile <name>.
All compile to ordinary session + policy + manifest behavior.
FINALIZED is a lifecycle state only — never serialized as artifact status. Artifact status values: COMPLETED, FAILED, CANCELED, INCOMPLETE.
governance/WORKFLOW_INVALID_TRANSITIONWORKFLOW_APPROVAL_REQUIREDWORKFLOW_SOURCE_REQUIREDWORKFLOW_TOOL_BUDGET_EXCEEDEDWORKFLOW_SESSION_TOKEN_INVALIDWORKFLOW_STARTER_INTEGRITY_ERRORThe canonical first-adopter path through v0.9.0-beta. No Bedrock, A2A, or OpenAI Agents SDK required.
aegis workflow init --profile minimal. A governance/ directory
is created with policy.yaml, workflow_example.py, and a manifest.
python workflow_example.py from inside governance/.
Expect Status: COMPLETED, a session UUID, and a PASS audit artifact on disk.
.jsonl artifact. Verify checksums, verdict, session correlation, and provenance metadata.
Use aegis workflow trace to reconstruct the timeline.
aegis workflow doctor to get human-readable diagnosis of the failure.
Run aegis workflow lint to check the policy and workflow config for structural issues.
Eleven labs walk you through every major capability in the shipped runtime. Each lab runs against a live FastAPI backend — no mocking, no fake responses. Use the lab cards below to jump directly to a specific topic, or open the full demo.
The demo runs against a permanent FastAPI backend. All 11 labs make real API calls — no mocked responses, no pre-baked results. Labs 1–10 cover v0.3.x capabilities from the shipped PyPI release. Lab 11 covers the v0.9.0-beta workflow governance surface.
One invocation, one artifact. Every governance outcome — pass or fail — is recorded with canonical checksums. Artifacts can be signed, chained, exported, and inspected offline.
ProvenanceGate blocks output when source context is absent.
RiskHistory tracks risk scores over time and flags improving,
stable, or degrading trajectories.
In workflow mode, invocation artifacts gain additive workflow-correlation metadata
(session_id, step_id, participant_id).
Raw external payloads are not persisted by default.
Workflow/session evidence is a separate artifact, not a replacement for per-invocation artifacts.
The installable runtime SDK is the Python package under aegis/.
Everything else in the repository is documentation, demo, test, or maintainer material
and is not required for runtime use.
Host code must never import from aegis._internal.
The _internal package is private by convention and required by public modules,
but it is not a stable API surface. All public exports are available from aegis directly.
# ✓ correct from aegis import enforce_invocation, AEGIS, governed # ✗ never do this in host code # from aegis._internal.enforcement import ...
Optional adapters normalize provider-specific trace formats and agent protocols into AEGIS evidence. They are advanced follow-on tracks — not required for the default first-adopter path.
openai-agents run, interruption, and optional trace evidence.
Governed tool support requires adapter-managed wrappers.
Included in the v0.9.0b1 public beta under aegis.openai_agents_adapter.
aegis. Requires the openai-agents
install extra. Unsupported runtime surfaces reject explicitly — no silent fallback.
aegis.bedrock_adapter; no AWS SDK is required by the base install.
supportedInterfaces[].protocolVersion.
Accepts only normative TASK_STATE_* wire values. gRPC is out of scope for v0.9.0.
aegis.a2a_adapter; no A2A SDK is required by the base install.
The first-adopter docs order puts adapter documentation last for a reason. Completing the local minimal-starter golden path — install → init → PASS → failure → doctor → fix → PASS again — requires none of these adapters. Add adapter complexity only after the default path is working and understood.
Install the SDK, read the quickstart, and run a local workflow starter. No external services, no API keys, no platform account.
pip install aegis-ai-governance==0.9.0b1 — install the public beta
docs/reference/WORKFLOW_QUICKSTART.md — first-adopter path
aegis workflow init --profile minimal — scaffold and execute