aegis-governance 1.1.0

AEGIS Governance Decision SDK — quantitative governance toolkit for engineering decisions

AEGIS Governance Decision SDK

Governance infrastructure for autonomous engineering decisions.

AEGIS standardizes engineering decisions and creates a hash-chained audit trail, giving enterprises the confidence to let AI agents operate autonomously. Evaluate proposals through six quantitative gates — returning structured PROCEED/PAUSE/ESCALATE/HALT decisions with tamper-evident audit trails.

Quickstart

pip install aegis-governance

Python SDK

from aegis_governance import AegisConfig, PCWContext, PCWPhase, PCWStatus, 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,
        quality_score=0.85,
    ),
    gate_evaluator=evaluator,
)

if decision.status == PCWStatus.PROCEED:
    print("Safe to proceed")
else:
    print(f"Decision: {decision.status.value} — {decision.rationale}")

CLI

# Evaluate a proposal
echo '{"proposal_summary":"Add caching","estimated_impact":"low","complexity_score":0.8}' \
  | aegis evaluate

# Validate configuration
aegis validate-config schema/interface-contract.yaml

# Version info
aegis version

Additional commands: aegis health, aegis metrics, aegis admin (customer management). Exit codes: 0 = proceed, 1 = halt, 2 = pause/escalate. See CLI Reference for full documentation.

MCP Server (for AI Agents)

pip install aegis-governance[mcp]
aegis-mcp-server  # Starts MCP server (stdio transport)

Exposes tools: aegis_evaluate_proposal, aegis_quick_risk_check, aegis_check_thresholds, aegis_get_scoring_guide, aegis_crypto_status.

What AEGIS Does

AEGIS runs proposals through six quantitative gates:

Gate	What It Checks
Risk	Is the risk delta acceptable? (Bayesian confidence)
Profit	Does the expected value justify the change? (Bayesian confidence)
Novelty	How novel is this approach? (Logistic scoring)
Complexity	Is system complexity within bounds? (Hard floor)
Quality	Does code quality meet standards? (Minimum + no zero subscores)
Utility	Is the net utility positive? (Lower confidence bound)

Every evaluation returns a structured decision with gate results, confidence scores, rationale, next steps, and a unique decision ID for audit trails.

Cryptography

AEGIS provides tamper-evident governance through three cryptographic capabilities:

• Two-key override signatures -- BIP-322 Schnorr or Ed25519 + ML-DSA-44 hybrid (post-quantum). Two custodians must independently sign before any gate override is approved. See Crypto Overview.
• PII encryption at rest -- 12 telemetry fields encrypted with X25519 + ML-KEM-768 + AES-256-GCM hybrid encryption. See Post-Quantum Rationale.
• MCP tool schema signing -- AMTSS protocol ensures tool definitions are tamper-evident in transit.

Key Management

AEGIS protects cryptographic keys at rest with envelope encryption:

Provider	Backend	Install
AWS KMS	boto3 KMS Encrypt/Decrypt	pip install aegis-governance[kms]
HSM (PKCS#11)	CloudHSM, YubiHSM 2, SoftHSM2	pip install aegis-governance[hsm]
Environment	Base64 env vars	Built-in

See Key Management Guide for setup and rotation.

Installation

# Core (zero runtime dependencies)
pip install aegis-governance

# With scipy for utility calculations (z-scores)
pip install aegis-governance[engine]

# With Prometheus metrics exporter
pip install aegis-governance[telemetry]

# With YAML config loading
pip install aegis-governance[config]

# With MCP server for AI agents
pip install aegis-governance[mcp]

# With post-quantum cryptography
pip install aegis-governance[crypto,pqc]

# With AWS KMS key management
pip install aegis-governance[kms]

# With HSM (PKCS#11) key management
pip install aegis-governance[hsm]

# Everything
pip install aegis-governance[all]

Configuration

AEGIS defaults match the frozen parameters in schema/interface-contract.yaml. Override via YAML or dict:

# From YAML (requires pyyaml)
config = AegisConfig.from_yaml("my-config.yaml")

# From dict
config = AegisConfig.from_dict({"epsilon_R": 0.02, "quality_min_score": 0.8})

# Config is immutable (frozen dataclass) — prevents parameter drift
config.epsilon_R = 0.5  # Raises AttributeError

Integration Layers

Layer	Interface	Consumer
Python SDK	from aegis_governance import pcw_decide	Python applications
CLI	aegis evaluate < proposal.json	CI/CD pipelines, shell scripts
REST API	POST /evaluate	Any language, HTTP clients
MCP Server	aegis_evaluate_proposal tool	Claude Code, Codex, AI agents
GitHub Action	aegis-gate composite action	PR governance gates

Compliance & Governance

AEGIS includes compliance infrastructure for regulatory frameworks:

• AI Governance (ai/) — ISO 42001, NIST AI RMF, EU AI Act artifacts
  • System register, risk register (OWASP Agentic Top 10), model/data cards
  • Human oversight plan, post-market monitoring, AIMS policy
  • EU AI Act Annex IV technical file
• Operational Runbooks (docs/compliance/) — SOC 2, FedRAMP procedures
  • System description, BCP/DRP, incident response plan
  • Access review, vendor risk, change management, privacy operations
• CI Validators (tools/ci/) — 9 compliance validators
  • AI RMF/AIMS artifacts, EU AI Act technical file structure
  • Log schema validation, engineering scorecard

Examples

See the examples/ directory:

• basic_evaluation.py — 20-line quickstart
• custom_config.py — YAML and dict configuration
• ci_cd_integration.py — GitHub Action usage
• autonomous_agent.py — AI agent + AFABridge

Development

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Quality gates (run all before committing)
make all  # Runs: lint, type, sec, test, ai-validate, scaffold-check

# Or run individually:
make fmt         # Auto-fix formatting
make lint        # Lint check (ruff + black)
make type        # Type check (mypy)
make test        # Test suite (pytest)
make sec         # Security scan (bandit)
make ai-validate # AI governance validators
make score       # Engineering scorecard

3713 tests | ~93.4% coverage | Python 3.9-3.12 | Zero runtime dependencies

Contributing

See CONTRIBUTING.md for full guidelines. Quick summary:

1. Read CLAUDE.md for repository conventions and agent guidance
2. All changes require tests (90% coverage floor enforced in pyproject.toml)
3. Follow {type}({scope}): {description} commit format (conventional commits)
4. Run make all before pushing (all quality gates must pass)
5. Frozen parameter changes require formal recalibration approval
6. Change classes: A (style), B (refactor), C (behavioral) — see CONTRIBUTING.md
7. AI-assisted contributions must include attribution in PR description

License

MIT License — See LICENSE for details.

References

• Documentation — Full documentation site
• Specification — Core guardrail specifications
• Interface Contract — Frozen parameters (authoritative)
• Architecture — Full system specification
• Gap Analysis — Component gap tracking
• CLI Reference — Full command-line documentation
• Roadmap — Future work
• Compliance Runbooks — Operational procedures (SOC 2, FedRAMP, EU AI Act)