Parameter Reference

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.6 (threshold).

Key transition points:

Important: The novelty gate passes for highly novel proposals (G(N) >= 0.6, meaning N >= ~0.74). 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. The utility_result field is optional — if not provided, all three entry surfaces (CLI, Lambda, MCP) auto-synthesize a UtilityResult from the flat profit_baseline/profit_proposed inputs using symmetric PERT three-point estimation (±20% spread). A profit delta epsilon clamp of 0.001 prevents zero-delta proposals from spuriously failing the strict LCB > 0.0 threshold.

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 that produces better estimates than the auto-synthesis. Most simple proposals should omit it and rely on auto-synthesis from profit/risk inputs. Provide it for investment decisions, capacity planning, or resource allocation where you can estimate expected value and uncertainty with domain-specific models.

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