Undercurrent
aegis-governance v1.0

AEGIS Governance SDK

Quantitative governance for engineering decisions. AEGIS evaluates proposals through six independent gates — Bayesian confidence, complexity analysis, quality metrics, and utility functions — returning structured PROCEED / PAUSE / ESCALATE / HALT decisions with cryptographic audit trails.

Install

bash
pip install aegis-governance
3,377Tests
~95%Coverage
3.9 – 3.12Python
ZeroRuntime Deps
6Gates

Why AEGIS?

Problem

"Should we ship this?" is a gut call

AEGIS Solution

Six quantitative gates with Bayesian confidence scoring

Problem

No audit trail for engineering decisions

AEGIS Solution

Every evaluation gets a unique decision_id, hash-chained audit log, and cryptographic signatures

Problem

Risk thresholds are tribal knowledge

AEGIS Solution

Configurable, frozen parameters with version-controlled YAML schemas

Problem

AI agents act without governance

AEGIS Solution

MCP server, GitHub Action, REST API, and CLI for agent-native integration

Get StartedFull DocumentationTry the Advisor

Quick Start

Get a governance decision in under 10 lines of code. Choose your preferred integration method below.

Installation

bash
pip install aegis-governance
Tip

AEGIS has zero runtime dependencies. Optional extras are available for crypto (pip install aegis-governance[crypto]), telemetry, and persistence.

Usage Examples

python
from aegis_governance import AegisConfig, PCWContext, PCWPhase, pcw_decide

config = AegisConfig.default()
evaluator = config.create_gate_evaluator()

decision = pcw_decide(
    PCWContext(
        agent_id="my-agent",
        session_id="session-1",
        phase=PCWPhase.PLAN,
        proposal_summary="Add Redis caching layer",
        estimated_impact="medium",
        risk_proposed=0.15,
        complexity_score=0.7,
    ),
    gate_evaluator=evaluator,
)

print(decision.status)       # PCWStatus.PROCEED
print(decision.decision_id)  # unique audit ID
print(decision.rationale)    # human-readable explanation

Verify the Result

Every evaluation returns a structured PCWDecision object with the decision status, confidence score, gate results, and a unique audit ID.

200 OKResponse
{
  "status": "proceed",
  "decision_id": "d-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "confidence": 0.97,
  "gates_passed": 6,
  "gates_failed": 0,
  "failing_gates": [],
  "rationale": "All 6 gates passed with high confidence.",
  "next_steps": ["Execute the proposed change."],
  "constraints": [],
  "override_eligible": false
}
statusOne of: "proceed", "pause", "escalate", "halt"
confidenceAggregate posterior confidence across all gates (0-1)
decision_idUnique identifier for audit trail lookups
failing_gatesList of gate names that did not pass
Note

The decision_id is your audit key. Every evaluation is logged with its full context, gate results, and timestamp for compliance and debugging.

Core Concepts

Every proposal flows through a six-gate evaluation pipeline. Each gate applies a distinct mathematical method to produce a quantitative pass/fail signal. The aggregate of all six gates determines the final decision: PROCEED, PAUSE, ESCALATE, or HALT.

Proposal
RiskProfitNoveltyComplexityQualityUtility
Decision

The Six Gates

Risk

Bayesian posterior> 0.95 confidence

Computes P(delta >= 2 | data) via conjugate Bayesian update to quantify risk confidence.

Profit

Bayesian posterior> 0.95 confidence

Evaluates expected profit contribution using the same Bayesian framework as the risk gate.

Novelty

Logistic function>= 0.8

Applies a logistic curve to novelty scores, rewarding innovation within safe bounds.

Complexity

Normalized floor>= 0.5

Ensures proposals don't exceed a complexity ceiling that would impede maintainability.

Quality

Min score + no zero subscores>= 0.7

Validates quality subscores (testing, docs, review) with a floor and no-zero policy.

Utility

Lower confidence bound> 0

Computes a lower-confidence-bound utility estimate, requiring net-positive expected value.

Decision Outcomes

PROCEEDAll gates pass — safe to execute
PAUSESome gates fail — review recommended
ESCALATECritical gates fail — human review required
HALTSevere failures — stop immediately

Confidence Scores

Each gate produces a confidence value between 0 and 1, representing the statistical strength of its evaluation. These per-gate confidence values are aggregated into an overall confidence score returned with every decision.

Tip

Confidence is not the probability of success. It is a statistical measure of how much evidence supports the gate's pass/fail determination. A confidence of 0.97 means the gate has strong statistical backing for its result, not that there is a 97% chance the proposal will succeed.

Read the full guide

Configuration

AEGIS ships with sensible defaults. Override any parameter via YAML or constructor.

Defaults

python
from aegis_governance import AegisConfig

# Use built-in defaults
config = AegisConfig.default()

# Inspect values
config.risk_trigger_factor       # 2.0
config.trigger_confidence_prob   # 0.95
config.complexity_floor          # 0.5
config.quality_min_score         # 0.7
config.novelty_threshold         # 0.8
config.utility_threshold         # 0.0

YAML Loading

aegis.yaml
parameters:
  risk_gate:
    trigger_factor: 2.5
    confidence_threshold: 0.90
  complexity_gate:
    floor: 0.6
  quality_gate:
    floor: 0.75
  novelty_gate:
    output_threshold: 0.85
python
config = AegisConfig.from_yaml("aegis.yaml")

Parameter Reference

ParameterTypeRequiredDefaultDescription
risk_trigger_factorfloatOptional2.0Multiplier for Bayesian risk posterior threshold
trigger_confidence_probfloatOptional0.95Minimum posterior confidence for risk and profit gates
complexity_floorfloatOptional0.5Minimum normalized complexity score to pass
quality_min_scorefloatOptional0.7Minimum quality score (0-1) to pass the gate
novelty_thresholdfloatOptional0.8Logistic output threshold for novelty gate
utility_thresholdfloatOptional0.0Lower confidence bound floor for utility gate
mcp_rate_limitintOptional60MCP server rate limit (requests per minute, 0 to disable)
Note

All parameters are frozen dataclass fields. Modify only via constructor or YAML — runtime mutation is not supported.

Read the full guide

Python SDK

The Python SDK is the primary interface. Import pcw_decide, build a PCWContext, and get a structured PCWDecision back.

pcw_decide()

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

config = AegisConfig.default()
evaluator = config.create_gate_evaluator()

decision = pcw_decide(
    PCWContext(
        agent_id="deploy-bot",
        session_id="session-42",
        phase=PCWPhase.PLAN,
        proposal_summary="Add Redis caching layer",
        estimated_impact="medium",
        risk_proposed=0.15,
        complexity_score=0.7,
    ),
    gate_evaluator=evaluator,
)

print(decision.status)       # PCWStatus.PROCEED
print(decision.decision_id)  # "d-a1b2c3..."
print(decision.rationale)    # human-readable explanation

PCWContext Fields

ParameterTypeRequiredDefaultDescription
agent_idstrRequired—Unique identifier for the calling agent
session_idstrRequired—Session or conversation identifier
phasePCWPhaseRequired—Workflow phase: PLAN, COMMIT, WORK
proposal_summarystrRequired—Human-readable description of the proposal
estimated_impactstrRequired—Impact level: low, medium, high, critical
risk_proposedfloatOptional0.0Risk score (0-1) for the proposal
complexity_scorefloatOptional0.5Complexity score (0-1)
quality_scorefloatOptional0.7Aggregate quality score (0-1)
quality_subscoreslist[float]Optional[0.7, 0.7, 0.7]Quality sub-metric scores (testing, docs, review)
novelty_scorefloatOptional0.5Novelty score (0-1)
profit_proposedfloatOptional0.0Expected profit of the proposed change (0-1)

PCWDecision Response

200 OKResponse
{
  "status": "proceed",
  "decision_id": "d-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "confidence": 0.97,
  "gates_passed": 6,
  "gates_failed": 0,
  "failing_gates": [],
  "rationale": "All 6 gates passed with high confidence.",
  "next_steps": ["Execute the proposed change."],
  "constraints": [],
  "timestamp": "2026-03-01T12:00:00+00:00",
  "override_eligible": false
}
statusOne of: "proceed", "pause", "escalate", "halt"
confidenceAggregate posterior confidence (0-1)
failing_gatesList of gate names that did not pass
gates_failedCount of gates that did not pass
Shadow Mode

Pass shadow_mode=True to pcw_decide() to evaluate without affecting production telemetry. Returns a ShadowResult with drift analysis.

Read the full guide

REST API

AEGIS is deployed as a Lambda-backed API Gateway. Three endpoints are available.

POST /evaluate

The primary evaluation endpoint. Submit a proposal with risk, complexity, quality, and novelty inputs to receive a full six-gate governance decision.

bash
curl -X POST https://your-api-gateway.amazonaws.com/dev/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "proposal_summary": "Add Redis caching layer",
    "estimated_impact": "medium",
    "risk_proposed": 0.15,
    "complexity_score": 0.7,
    "quality_subscores": [0.9, 0.8, 0.85]
  }'
200 Response
{
  "status": "proceed",
  "decision_id": "d-a1b2c3d4",
  "confidence": 0.97,
  "gates_passed": 6,
  "gates_failed": 0,
  "failing_gates": [],
  "rationale": "All 6 gates passed.",
  "next_steps": ["Execute the proposed change."],
  "constraints": [],
  "override_eligible": false
}

POST /risk-check

A lighter endpoint for quick risk threshold checks. Compares a risk score against a threshold without running the full gate pipeline.

bash
curl -X POST https://your-api-gateway.amazonaws.com/dev/risk-check \
  -H "Content-Type: application/json" \
  -d '{"risk_score": 0.4, "threshold": 0.5}'
200 Response
{
  "safe": true,
  "risk_score": 0.4,
  "threshold": 0.5,
  "agent_id": "lambda-caller"
}

GET /health

Health check endpoint. Returns service status and version.

bash
curl https://your-api-gateway.amazonaws.com/dev/health
200 Response
{
  "status": "healthy",
  "version": "1.0.0",
  "stage": "dev",
  "config_loaded": true
}
Note

The production API requires AWS IAM Signature V4 authentication. For local development, use the Python SDK or CLI directly.

Read the full guide

CLI Reference

The aegis CLI provides governance evaluation directly from your terminal.

aegis evaluate

Evaluate a proposal through all 6 gates. Pass input as a JSON file (--input) or pipe JSON to stdin.

bash
# Evaluate from a JSON file
aegis evaluate --input proposal.json

# Pipe JSON via stdin
echo '{
  "proposal_summary": "Add Redis caching layer",
  "estimated_impact": "medium",
  "risk_proposed": 0.15,
  "complexity_score": 0.7
}' | aegis evaluate

# With custom config and shadow mode
aegis evaluate --config aegis.yaml --shadow

# With telemetry and drift detection
aegis evaluate --input proposal.json \
  --telemetry-url https://telemetry.example.com \
  --drift-baseline baseline.json

Other Commands

bash
# Check AEGIS version
aegis version

# Health check (verifies dependencies)
aegis health

# Validate a YAML config file
aegis validate-config aegis.yaml

# Dump Prometheus metrics
aegis metrics
Tip

The CLI outputs JSON by default. Pipe to jq for pretty-printing: aegis evaluate --input proposal.json | jq .

Read the full guide

MCP Server

The MCP (Model Context Protocol) server lets AI agents call AEGIS governance tools directly. Supports stdio and HTTP transports.

Setup

bash
# Install
pip install aegis-governance

# Start stdio server (default)
aegis-mcp-server

# Start HTTP server
aegis-mcp-server --transport http --port 8080

Available Tools

The MCP server exposes four tools that AI agents can invoke via the standard tool-calling protocol.

aegis_evaluate_proposal

Full governance evaluation through all 6 gates. Accepts proposal summary, impact, risk, complexity, quality subscores, and novelty score.

aegis_quick_risk_check

Quick risk threshold check. Accepts risk_score and optional threshold.

aegis_check_thresholds

Introspect all 6 gate thresholds and current configuration. Call before submitting proposals to understand gate behavior.

aegis_get_scoring_guide

Get parameter derivation guidance for a specific domain. Returns formulas, examples, and range guides.

Agent Configuration

json
{
  "mcpServers": {
    "aegis": {
      "command": "aegis-mcp-server",
      "args": []
    }
  }
}
Note

Rate limiting defaults to 60 requests per minute. Adjust via mcp_rate_limit in your AegisConfig.

Read the full guide

GitHub Action

Add AEGIS as a governance gate in your CI/CD pipeline with the reusable composite action.

Workflow Example

.github/workflows/governance.yml
name: Governance Gate
on: [pull_request]

jobs:
  aegis-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: undercurrent-holdings/aegis-governance/.github/actions/aegis-gate@main
        with:
          proposal: ${{ github.event.pull_request.title }}
          impact: medium
          risk_score: "0.2"

Inputs & Outputs

Inputs
ParameterTypeRequiredDefaultDescription
proposalstringRequired—Proposal summary (usually the PR title)
impactstringRequired—Impact level: low, medium, high, critical
risk_scorestringOptional0.0Risk score as string (0–1)
complexitystringOptional0.0Complexity score as string (0–1)
config_pathstringOptional—Path to custom aegis.yaml config file
Outputs
ParameterTypeRequiredDefaultDescription
statusstringOptional—Decision status: proceed, pause, escalate, halt
decision_idstringOptional—Unique audit identifier for the evaluation
confidencestringOptional—Aggregate confidence score
Warning

The action will fail the workflow step if the decision is HALT or ESCALATE. PAUSE decisions pass with a warning annotation.

Read the full guide

Resources & Full Docs

This portal covers the essentials. For deep-dive reference documentation, deployment guides, compliance frameworks, and architecture decisions, visit the full documentation site.

Open Full Documentation
Full Documentation

Complete reference docs — API reference, deployment guides, architecture, compliance.

Python SDK Reference

Detailed pcw_decide() reference, PCWContext fields, AegisConfig options, shadow mode.

REST API Reference

Endpoint schemas, authentication, request/response examples, error codes.

MCP Tools Reference

MCP server setup, tool schemas, transport options, rate limiting.

GitHub Repository

Source code, issues, and contribution guidelines.

PyPI Package

Install via pip. Published releases and version history.

Changelog

Release notes, breaking changes, and migration guides.

Deployment Guide

Docker, Kubernetes, AWS Lambda/ECS deployment, observability, HSM.

Try the AdvisorContact Us