AgoraIV -- AEGIS Integration Contract

Version: 1.1.0 | Updated: 2026-02-26 | Status: Active GAP Reference: GAP-7 (AgoraIV Integration Contract) AEGIS Version: v1.1.0 (aegis-governance package) AgoraIV Component: aegis_bridge/ module

1. Overview

AgoraIV orchestrates multi-model LLM dialogue across GPT-5.2, Claude Opus 4.6, and Gemini 3 via the PCW V3 (PowerCommunalWisdom Version 3) consensus protocol. AEGIS provides quantitative governance gates that evaluate research outputs before they are routed to decision logic.

The integration boundary lives in aegis_bridge/ within the AgoraIV codebase. This bridge module adapts AgoraIV research outputs into AEGIS gate inputs and converts AEGIS gate results back into AgoraIV's internal decision-routing types.

AgoraIV (multi-model orchestration)
    |
    +-- aegis_bridge/          <-- Integration boundary (AgoraIV-owned)
    |       |
    |       +-- ResearchToAegisMapper    Converts research outputs -> AEGIS params
    |       +-- AegisGateResult          Internal gate result type
    |       +-- GateType (AgoraIV)       Maps to AEGIS GateType enum
    |       +-- evaluate()               Calls GateEvaluator.evaluate_all()
    |       +-- fallback_evaluate()      Degraded mode when AEGIS unavailable
    |
    +-- decision_engine/       <-- Consumes gate results for routing

Relationship: AEGIS is a governance dependency of AgoraIV. AEGIS does not depend on AgoraIV. This contract is unidirectional: AgoraIV calls AEGIS, never the reverse.

2. AEGIS Version Requirements

Import Mechanism

Resolved (GAP-1): AgoraIV now imports AEGIS via pip install aegis-governance[engine] (or pip install -e path/to/aegis-governance[engine] for development). The aegis_governance package exposes a stable public API via src/aegis_governance/__init__.py. The previous sys.path hack has been removed from aegis_bridge/gate_adapter.py and replaced with standard pip imports. The dependency is declared in requirements_agora.txt.

3. Gate Evaluation

AEGIS evaluates all 6 quantitative gates for every AgoraIV research proposal. The bridge calls GateEvaluator.evaluate_all() and receives a GateEvaluationResult containing individual GateResult objects keyed by GateType.

3.1 Gates Evaluated

GAP-3 (Resolved): The PROFIT gate result is now mapped to GateType.PROFIT and passed through to the AgoraIV decision engine as an advisory gate.

3.2 Mandatory vs Advisory Classification

The bridge classifies gate results into two enforcement tiers before passing them to the AgoraIV decision engine.

Mandatory Gates (failure halts or blocks the proposal)

Advisory Gates (failure triggers review, not halt)

4. Data Flow

4.1 Normal Path (AEGIS Available)

AgoraIV PCW V3 Research Outputs
         |
         v
 ResearchToAegisMapper.map(research_output)
         |  Extracts: risk_baseline, risk_proposed, profit_baseline,
         |  profit_proposed, novelty_score, complexity_score,
         |  quality_score, quality_subscores, proposal_summary,
         |  estimated_impact
         v
 GateEvaluator.evaluate_all(
     risk_baseline=...,
     risk_proposed=...,
     profit_baseline=...,
     profit_proposed=...,
     novelty_score=...,
     complexity_score=...,
     quality_score=...,
     quality_subscores=[...],
 )
         |
         v
 GateEvaluationResult
     .gates[GateType.RISK]      -> GateResult(passed, value, threshold, ...)
     .gates[GateType.PROFIT]    -> GateResult(passed, value, threshold, ...)
     .gates[GateType.NOVELTY]   -> GateResult(passed, value, threshold, ...)
     .gates[GateType.COMPLEXITY]-> GateResult(passed, value, threshold, ...)
     .gates[GateType.QUALITY]   -> GateResult(passed, value, threshold, ...)
     .gates[GateType.UTILITY]   -> GateResult(passed, value, threshold, ...)
         |
         v
 Bridge converts to AegisGateResult objects
     (all 6 gates mapped including PROFIT)
         |
         v
 AgoraIV DecisionEngine.route(gate_results)
     Applies mandatory/advisory classification
     Routes to: execute | review | halt

4.2 Degraded Path (AEGIS Unavailable)

When the AEGIS package cannot be imported (AEGIS_AVAILABLE = False), the bridge degrades to simplified threshold comparisons. This ensures AgoraIV continues functioning but with reduced governance rigor.

# Simplified fallback logic (approximate representation)
def fallback_evaluate(research_output):
    results = {}
    if research_output.risk_score < 0.5:
        results["risk"] = PASS
    else:
        results["risk"] = FAIL

    if research_output.quality_score >= 0.7:
        results["quality"] = PASS
    else:
        results["quality"] = FAIL

    if research_output.complexity_score >= 0.5:
        results["complexity"] = PASS
    else:
        results["complexity"] = FAIL

    # Novelty and utility use simple thresholds
    # No Bayesian posterior, no logistic function, no LCB
    return results

Limitations of fallback mode:

Expectation: Fallback mode is acceptable for development and testing. Production deployments MUST have AEGIS available. The bridge SHOULD log a warning at startup when operating in fallback mode.

5. Audit Requirements

5.1 Current State (GAP-2 Resolved)

The bridge now uses AuditMiddleware.decide() for audit trail emission after each gate evaluation. The GateAdapter creates an AuditMiddleware(source="agoraiv") instance at construction and calls _emit_audit_event() after every successful evaluation.

This provides:

• Automatic input validation (NaN/Inf rejection, bool guarding, type coercion).
• Audit event emission with SHA-256 integrity hashes.
• Drift detection via DriftMonitor integration (GAP-4 resolved).
• Rate limiting (when configured).
• Consistent behavior with MCP, Lambda, and CLI entry points.

5.2 Implementation Pattern

from aegis_governance import AuditMiddleware, DriftMonitor, build_pcw_context

audit = AuditMiddleware(source="agoraiv")
drift_monitor = DriftMonitor()

# After gate evaluation, emit audit event with drift context
ctx = build_pcw_context({
    "agent_id": "agoraiv-bridge",
    "phase": "work",
    "risk_baseline": mapped.risk_baseline,
    "risk_proposed": mapped.risk_proposed,
    "profit_baseline": mapped.profit_baseline,
    "profit_proposed": mapped.profit_proposed,
    "novelty_score": mapped.novelty_score,
    "complexity_score": mapped.complexity_score,
    "quality_score": mapped.quality_score,
    "quality_subscores": mapped.quality_subscores,
    "metadata": {"source": "agoraiv-gate-adapter", "drift_baseline_data": drift_history},
})

decision = audit.decide(ctx, drift_monitor=drift_monitor)

5.3 Audit Event Schema

Each AuditMiddleware.decide() call emits an AuditEvent containing:

6. Parameter Mapping Reference

The ResearchToAegisMapper MUST produce values conforming to AEGIS parameter constraints. See Parameter Reference for full derivation guidance.

Input validation: All float parameters MUST be finite (not NaN, not Inf). Boolean values MUST NOT be passed where floats are expected. The AuditMiddleware and build_pcw_context() enforce these constraints; direct GateEvaluator calls do not.

7. Shared Testing Responsibility

7.1 AEGIS Owns

7.2 AgoraIV Owns

7.3 Shared (Cross-Project)

Contract tests (GAP-5) verify the AEGIS public API surface against AgoraIV's requirements. These run in AEGIS CI automatically.

8. Known Gaps

Resolution Priority

Phase 1 (Immediate) — RESOLVED 2026-02-26:
  GAP-1: ✅ aegis-governance pip-installable, sys.path hack removed
  GAP-2: ✅ Bridge uses AuditMiddleware.decide() for audit trail

Phase 2 (Short-term) — RESOLVED 2026-02-26:
  GAP-3: ✅ PROFIT gate mapped as advisory tier
  GAP-4: ✅ drift_baseline_data passed via DriftMonitor integration
  GAP-5: ✅ 67 contract tests in tests/integration/test_agoraiv_contract.py

Phase 3 (Backlog):
  GAP-6: Load fallback thresholds from interface-contract.yaml
  GAP-8: Add shadow_mode passthrough to bridge

9. Compatibility and Versioning

AEGIS SDK Stability Guarantees

The aegis_governance public API (everything in __all__ of src/aegis_governance/__init__.py) follows semantic versioning:

• PATCH (1.0.x): Bug fixes, no API changes. AgoraIV bridge SHOULD upgrade without changes.
• MINOR (1.x.0): New features, backward-compatible. AgoraIV bridge MAY need updates to use new capabilities.
• MAJOR (x.0.0): Breaking changes. AgoraIV bridge MUST be updated.

Frozen Parameters

Gate threshold values in schema/interface-contract.yaml are frozen at guardrail-v1.1-freeze. These values MUST NOT change without formal recalibration approval. AgoraIV MAY rely on these values being stable across AEGIS patch and minor versions.

If AgoraIV's fallback mode hardcodes threshold values, those values MUST match the frozen parameters:

10. Contact and Ownership

Escalation path: Changes to the AEGIS SDK public surface that affect AgoraIV MUST be communicated to the AgoraIV team before release. Changes to schema/interface-contract.yaml frozen values require Risk Lead approval per AEGIS governance policy (CLAUDE.md SS 2).

References

• AEGIS Parameter Reference -- Full parameter semantics and derivation guidance
• AEGIS Domain Templates -- Worked integration examples
• Interface Contract -- Frozen parameter values (authoritative)
• AEGIS Middleware -- AuditMiddleware, validation helpers
• Gap Analysis -- Full AEGIS component gap inventory
• Production Guide -- AEGIS deployment and observability
• Unified AEGIS Specification -- Complete system architecture

Changelog