AEGIS Parameter Reference Guide¶

Version: 1.0.0 | Updated: 2026-02-12 | Status: Active

This guide provides complete parameter documentation for the AEGIS Governance Decision SDK. It covers every input parameter, configuration value, and decision output — with derivation guidance, domain examples, and boundary behavior.

Audience: Integration engineers, AI agent developers, platform teams, risk analysts.

Authoritative sources: schema/interface-contract.yaml (frozen values), src/config.py (AegisConfig), src/engine/gates.py (gate logic), src/integration/pcw_decide.py (decision flow).

Interactive guidance: For domain-specific derivation formulas and worked examples via MCP, call aegis_get_scoring_guide(domain) — available for trading, cicd, moderation, agents, and generic domains.

Quick Reference Table¶

1. Proposal Context Parameters¶

1.1 proposal_summary¶

What it represents: A human-readable description of the proposed action. Stored in the audit trail and telemetry events.

• Type: string (non-empty)
• Used by: Telemetry, audit trail, decision rationale
• Tip: Keep it specific enough for an auditor to understand the proposal months later.

1.2 estimated_impact¶

What it represents: The blast radius of the proposal — how much of the system could be affected if something goes wrong.

1.3 agent_id¶

What it represents: Identifier of the AI agent or user making the proposal. Recorded in telemetry and audit trail for accountability.

• Default: "aegis-cli" (CLI), "mcp-agent" (MCP)
• Best practice: Use a stable identifier (e.g., "claude-code-v4", "codex-pr-reviewer", "deploy-bot-prod")

session_id is auto-generated (UUID) if not provided. Use it to correlate multiple decisions within a single agent session.

2. Risk Parameters¶

The risk gate uses Bayesian posterior evaluation: P(delta >= trigger_factor | data) > confidence_threshold.

2.1 risk_baseline¶

What it represents: The current risk level before the proposed change.

• Range: 0.0 - 1.0
• Default: 0.0 (no existing risk)
• Units: Dimensionless probability / normalized ratio

How to derive it:

Boundary behavior: - risk_baseline = 0.0: Any non-zero proposed risk triggers the gate (0 to anything is an infinite multiplier, but epsilon_R=0.01 prevents division by zero) - risk_baseline = risk_proposed: Delta is 0, gate always passes

2.2 risk_proposed¶

What it represents: The predicted risk level after the proposed change is applied.

• Range: 0.0 - 1.0
• Default: 0.0
• Alias: risk_score (MCP/CLI shorthand)

Gate math: The risk gate normalizes the delta as (risk_proposed - risk_baseline) / max(|risk_baseline|, epsilon_R) and computes a Bayesian posterior probability that this delta exceeds risk_trigger_factor (default: 2.0). If P(delta >= 2.0 | data) > 0.95, the gate fails.

Common mistakes: - Setting risk_proposed without setting risk_baseline — the gate compares the two, so both matter - Using values > 1.0 — the gate accepts them but they indicate the normalization is wrong

3. Profit Parameters¶

The profit gate mirrors the risk gate (Bayesian posterior) but measures performance improvement.

3.1 profit_baseline¶

What it represents: Current performance/profit metric before the change.

• Range: Any real number (not normalized to 0-1)
• Default: 0.0
• Units: Domain-specific

3.2 profit_proposed¶

What it represents: Expected performance/profit after the change.

• Range: Any real number
• Default: 0.0

Gate math: Same as risk — (profit_proposed - profit_baseline) / max(profit_baseline, epsilon_P). The gate triggers when performance drops by a factor of profit_trigger_factor (default: 2.0) with 95% confidence.

Note: The profit gate detects decreases in performance, not increases. A positive delta (improvement) always passes.

4. Novelty Score¶

What it represents: How unprecedented or novel the proposal is. Higher novelty means more scrutiny.

• Range: 0.0 (routine/well-understood) to 1.0 (completely novel)
• Default: 0.5

Gate math: Logistic function G(N) = 1 / (1 + exp(-k * (N - N0))) where N0=0.7 (inflection point) and k=10 (steepness). The gate passes when G(N) >= 0.8 (threshold).

Key transition points:

Important: The novelty gate passes for highly novel proposals (G(N) >= 0.8, meaning N >= ~0.84). Proposals with low novelty fail this gate. This reflects the spec's design that proposals should demonstrate sufficient novelty to warrant consideration. If your domain treats high novelty as a risk factor, consider using 1.0 - your_novelty_metric as the novelty_score input.

How to derive it:

Common mistakes: - Setting novelty_score = 1.0 for every new feature. Reserve 0.9+ for truly unprecedented changes - Confusing novelty with risk. A novel change can be low-risk (new but safe pattern)

5. Complexity Score¶

What it represents: Normalized complexity where HIGHER = SIMPLER. This is counterintuitive by design — it measures "simplicity headroom" above the complexity floor.

• Range: 0.0 (maximally complex) to 1.0 (trivial)
• Default: 0.5

Gate math: Hard floor at complexity_floor = 0.5. If complexity_score < 0.5, the proposal receives a HALT status that cannot be overridden.

Why HIGHER = SIMPLER?: The gate evaluates complexity_score >= floor. This means the score represents "how far above the complexity limit" the proposal is — essentially "simplicity margin."

How to derive it:

complexity_score = 1.0 - (raw_complexity / max_complexity)

Boundary behavior: - complexity_score = 0.49: HALT, non-overridable (below floor) - complexity_score = 0.50: Pass (at floor) - complexity_score = 1.0: Pass (trivially simple)

Common mistakes: - Passing raw complexity (e.g., LOC count) without normalizing to 0-1 - Forgetting that this is an inverted scale

6. Quality Score¶

What it represents: Overall quality assessment of the proposal.

• Range: 0.0 - 1.0
• Default: 0.7
• Threshold: Must be >= 0.7 (quality_min_score)

quality_subscores: Optional array of per-dimension quality scores. If provided: - Each must be 0.0-1.0 - No zero rule: If quality_no_zero_subscore is true (default), any zero subscore fails the gate

How to derive it:

Boundary behavior: - quality_score = 0.69: Fail (below threshold) - quality_score = 0.70: Pass - quality_subscores = [0.9, 0.0, 0.8]: Fail (zero subscore)

7. Utility Parameters¶

The utility gate uses the Lower Confidence Bound (LCB) of a utility function. It is optional — if utility_result is not provided, the gate auto-passes.

UtilityResult dataclass fields:

Gate math: LCB = mean - z_{1-alpha/2} * sqrt(variance) where alpha=0.05 (95% confidence). Gate passes if LCB > utility_threshold (default: 0.0).

When to provide it: Only when you have a quantitative utility model. Most simple proposals should omit it (auto-pass). Provide it for investment decisions, capacity planning, or resource allocation where you can estimate expected value and uncertainty.

Common mistake: Providing a UtilityResult with high variance and low mean. The LCB will be very negative, causing a gate failure even with positive expected utility.

8. Execution Context Flags¶

shadow_mode: Use during calibration periods (30+ days recommended). Shadow mode still records telemetry and drift observations but does not enforce HALT/PAUSE decisions. The decision result includes a shadow_result object with observation values and baseline hash.

9. Drift Detection¶

KL divergence drift detection compares current observations against a historical baseline distribution.

drift_baseline_data¶

• Type: Array of numbers (float)
• Minimum: 30+ values recommended (fewer produces unreliable KL divergence)
• Default: None (drift detection disabled)

Gate behavior:

How to derive baseline data: Collect 30+ historical metric observations from production. These should represent the "normal" operating distribution of whatever metric you're monitoring (e.g., error rates, latency percentiles, throughput values).

10. Configuration Parameters¶

These are set via AegisConfig (YAML, dict, or defaults) and control gate behavior.

Gate Thresholds¶

Utility Function Parameters¶

Drift Detection Parameters¶

Operational Parameters¶

11. Decision Status Reference¶

Override eligibility: A decision is override-eligible when failing gates are all overridable. The complexity floor gate is never overridable. Drift CRITICAL is overridable but requires explicit re-baseline.

Appendix A: Parameter Derivation Flowchart¶

1. Identify your domain metrics
   └─ What do you measure? (error rate, VaR, throughput, etc.)

2. Map to AEGIS parameters
   └─ risk_baseline/proposed → your risk metric (normalized 0-1)
   └─ profit_baseline/proposed → your performance metric
   └─ novelty_score → similarity to past actions (inverted)
   └─ complexity_score → 1.0 - (raw_complexity / max_complexity)
   └─ quality_score → composite quality signal

3. Set estimated_impact
   └─ How much could go wrong? → low/medium/high/critical

4. Collect drift baseline (optional)
   └─ 30+ historical observations of your key metric

5. Start in shadow_mode for 30+ days
   └─ Calibrate thresholds before enforcing

Appendix B: Frozen Parameters (interface-contract.yaml)¶

All gate threshold values are frozen in schema/interface-contract.yaml. They cannot be changed at runtime (AegisConfig is a frozen dataclass). Changes require formal recalibration approval per AEGIS governance policy.

To inspect current values programmatically:

from aegis_governance import AegisConfig
config = AegisConfig.default()
print(config.to_dict())

Or via MCP:

{"method": "tools/call", "params": {"name": "aegis_check_thresholds", "arguments": {}}}

References¶

• Interface Contract — Frozen parameter values
• Domain Templates — Worked examples for 4 domains
• Production Guide — Deployment and observability
• AEGIS Specification — Full system specification