Skip to content

Python SDK Quickstart

This guide walks you through your first governance evaluation using the AEGIS Python SDK.

Prerequisites

pip install aegis-governance

Basic Evaluation

Every governance decision flows through pcw_decide(). Create a context describing the proposed action, pass it to the evaluator, and inspect the decision.

from aegis_governance import (
    AegisConfig,
    PCWContext,
    PCWPhase,
    PCWStatus,
    pcw_decide,
)

# 1. Load configuration (defaults match frozen parameter values)
config = AegisConfig.default()

# 2. Create a gate evaluator from the config
evaluator = config.create_gate_evaluator()

# 3. Build the proposal context
context = PCWContext(
    agent_id="my-agent",
    session_id="session-001",
    phase=PCWPhase.PLAN,
    proposal_summary="Add Redis caching layer to reduce API latency",
    estimated_impact="medium",
    risk_proposed=0.3,
    complexity_score=0.6,
)

# 4. Evaluate
decision = pcw_decide(context, gate_evaluator=evaluator)

# 5. Act on the result
if decision.status == PCWStatus.PROCEED:
    print("Safe to proceed")
elif decision.status == PCWStatus.PAUSE:
    print("Paused for human review")
elif decision.status == PCWStatus.HALT:
    print("Halted — see rationale")

Reading Decision Results

The PCWDecision object returned by pcw_decide() contains everything you need to act on and audit the decision.

print(f"Status:       {decision.status.value}")
print(f"Confidence:   {decision.confidence:.2f}")
print(f"Gates passed: {decision.gates_passed}")
print(f"Gates failed: {decision.gates_failed}")
print(f"Rationale:    {decision.rationale}")
print(f"Next steps:   {decision.next_steps}")
print(f"Decision ID:  {decision.decision_id}")
print(f"Timestamp:    {decision.timestamp.isoformat()}")

# Per-gate details (when gate_evaluator is provided)
if decision.gate_evaluation:
    for gate_type, result in decision.gate_evaluation.gates.items():
        print(f"  {gate_type.value}: passed={result.passed}, "
              f"value={result.value:.4f}, threshold={result.threshold:.4f}")

Configuration from YAML

Load parameters from your own YAML configuration file instead of using the built-in defaults. The file follows the same structure as schema/interface-contract.yaml.

config = AegisConfig.from_yaml("my-config.yaml")
evaluator = config.create_gate_evaluator()
decision = pcw_decide(context, gate_evaluator=evaluator)

Example YAML file:

parameters:
  epsilon_R: 0.01
  epsilon_P: 0.01
  risk_trigger_factor: 2.0
  profit_trigger_factor: 2.0
  trigger_confidence_prob: 0.95
  complexity_floor: 0.5
  quality_min_score: 0.7

  novelty_gate:
    N0: 0.7
    k: 10.0
    output_threshold: 0.8

  utility:
    gamma: 0.3
    kappa: 1.0
    lcb_alpha: 0.05
    theta: 0.0

  kl_drift:
    tau_warning: 0.3
    tau_critical: 0.5
    window_days: 30

Shadow Mode

Shadow mode evaluates the proposal through all gates and collects drift telemetry without enforcing the decision. Use it to calibrate baselines or validate gate behavior before going live.

decision = pcw_decide(
    context,
    gate_evaluator=evaluator,
    shadow_mode=True,
)

# The decision is computed normally, but marked shadow-only
if decision.shadow_result is not None:
    print(f"Shadow only:        {decision.shadow_result.shadow_only}")
    print(f"Observation values: {decision.shadow_result.observation_values}")
    print(f"Baseline hash:      {decision.shadow_result.baseline_hash}")

    if decision.shadow_result.drift_result:
        dr = decision.shadow_result.drift_result
        print(f"Drift status: {dr.status.value}, KL={dr.kl_divergence:.4f}")

Drift Monitoring

Provide a DriftMonitor with a calibrated baseline to detect when incoming proposals deviate from historical norms. In production mode, CRITICAL drift halts the decision; WARNING drift adds an advisory constraint.

# Create a drift monitor from config
drift_monitor = config.create_drift_monitor()

# Set the baseline from historical data
baseline_data = [0.1, 0.2, 0.15, 0.12, 0.18, 0.22, 0.14]
drift_monitor.set_baseline(baseline_data)

# Evaluate with drift enforcement
decision = pcw_decide(
    context,
    gate_evaluator=evaluator,
    drift_monitor=drift_monitor,
)

if decision.drift_result:
    print(f"Drift status: {decision.drift_result.status.value}")
    print(f"KL divergence: {decision.drift_result.kl_divergence:.4f}")
    print(f"Action: {decision.drift_result.action.value}")

Quick Risk Check

For simple threshold-based checks that do not require the full Bayesian gate pipeline, use quick_risk_check(). This is a convenience function, not a substitute for pcw_decide() in regulated environments.

from aegis_governance import quick_risk_check

is_safe = quick_risk_check(
    agent_id="my-agent",
    action_description="Update configuration file",
    risk_score=0.2,
    threshold=0.5,
)

if is_safe:
    print("Low risk — proceed")

Warning: quick_risk_check() performs a direct threshold comparison without Bayesian posterior evaluation. For decisions requiring audit trails or regulatory compliance, use pcw_decide().

Next Steps