API Reference

Complete SDK API documentation.

GovernanceSteward

Main class for evaluating agent actions against blueprints.

Spec mapping: - ACGP-1 Section 5 runtime summary - ACGP-1 Section 8 two-stage local/remote evaluation - ACGP-2 message semantics for TRACE, EVAL, INTERVENTION, HITL, SESSION_INIT, BUNDLE_UPDATE, VERSION_NEGOTIATION, VERSION_SELECTED - ACGP-3 Section 10 authoritative evaluation flow

General constructor

GovernanceSteward(
    blueprint_file: Optional[str] = None,
    blueprint_dict: Optional[Dict[str, Any]] = None,
    blueprint_id: Optional[str] = None,
    registry: Optional[BlueprintRegistry] = None,
    state_storage: Optional[StateStorage] = None,
    conformance_level: str = "dev_mode",
    enable_warnings: bool = True,
    deployment_mode: str = "development",
    require_production_posture: bool = False,
)

Use the general constructor for development, testing, and advanced bootstrap flows. For production deployments, prefer GovernanceSteward.production(...).

Parameters: - blueprint_file: Path to blueprint YAML file (loaded by steward at initialization) - blueprint_dict: Blueprint as dictionary (for testing/development) - blueprint_id: Blueprint ID to load from registry - registry: Blueprint registry client - state_storage: State storage for stateful tripwires; if omitted, the steward may select an in-memory backend that is unsuitable for production - conformance_level: dev_mode, standard, or safety-critical - enable_warnings: Enable production warnings for Dev Mode - deployment_mode: development, staging, or production - require_production_posture: Require production-safe runtime posture validation at startup

v1.0 profile naming

For v1.0.0-alpha.2, use Standard Conformant claims only. Dev Mode is the preferred public term for the non-conformant runtime mode, while the Python API value is dev_mode. Safety-Critical claim language is reserved for a future release per ACGP-6.

Alpha scope

Claim questions and badge semantics are owned by ACGP-6. This API reference documents runtime surfaces, not claim authority.

Blueprint Selection - Steward-Side

You must provide one of blueprint_file, blueprint_dict, or blueprint_id.

Important: Blueprints are configured on the steward, not by agents. The steward automatically selects the appropriate blueprint for each evaluation based on agent scope, inheritance rules, and request context. This maintains proper separation of concerns and prevents agents from bypassing governance.

production()

GovernanceSteward.production(
    *,
    state_storage: StateStorage,
    conformance_level: str = "standard",
    **kwargs: Any,
)

Recommended production bootstrap path.

  • requires an explicit durable state_storage
  • forces deployment_mode="production"
  • forces require_production_posture=True
  • rejects attempts to downgrade the production posture contract

Methods

evaluate()

evaluate(trace: CognitiveTrace, context: Optional[Dict[str, Any]] = None) -> InterventionResult

Evaluate a cognitive trace against the blueprint and return intervention recommendation.

Spec mapping: - ACGP-1 Section 5 (high-level runtime summary) - ACGP-1 Section 8 (stage boundaries and local-first behavior) - ACGP-3 Section 7 and Section 10 (threshold mapping + authoritative evaluation flow)

Parameters: - trace: CognitiveTrace object - context: Optional context dictionary

Returns: - InterventionResult with intervention type and message

For HITL escalations, the final agent-visible result is still an INTERVENTION. The human-review completion artifact is HITL_RESULT, which is consumed by the Steward rather than exposed as a separate wire message type. See ACGP-2 §5.5.

get_metrics()

get_metrics() -> Dict[str, Any]

Get governance metrics including evaluation counts and intervention statistics.

Spec mapping: - ACGP-5 audit and runtime observability artifacts

CognitiveTrace

Represents agent reasoning and planned action.

Spec mapping: - ACGP-3 Section 4 cognitive trace model - ACGP-2 Section 5.1 TRACE payload

Constructor

CognitiveTrace(
    reasoning: Optional[str] = None,
    action: str,
    parameters: Dict[str, Any] = {},
    confidence: Optional[float] = None,
    trace_id: Optional[str] = None,
    agent_id: Optional[str] = None,
    governance_tier: Optional[str] = None,
)

governance_tier is the canonical field.

InterventionResult

Result of governance evaluation.

Spec mapping: - ACGP-1 Section 3.3 intervention semantics - ACGP-2 Section 5.3 INTERVENTION payload

Attributes

  • intervention: InterventionType - One of OK, NUDGE, ESCALATE, BLOCK, HALT
  • message: str - Human-readable explanation
  • trace_id: str - ID of the evaluated trace
  • timestamp: datetime - When the evaluation completed
  • governance_status: Optional[GovernanceStatus] - Evaluation status details
  • metadata: Dict[str, Any] - Additional evaluation metadata

SourceBlueprint

Author-facing Blueprint source artifact loaded from YAML or dictionary before resolution.

Spec mapping: - ACGP-3 Section 2 Blueprint source artifact schema - ACGP-3 Section 8 evidence policy - ACGP-3 Section 9 trust policy core

Attributes

  • artifact_type: str - Source artifact discriminator (acgp.blueprint)
  • schema_version: str - Blueprint source schema version
  • id: str - Unique blueprint identifier (for example finance/trading@2.0)
  • version: str - Blueprint version (semantic versioning)
  • title: str - Human-readable blueprint title
  • description: str - Blueprint description
  • base: Optional[BaseReference] - Parent Blueprint reference for resolution
  • applicability: Optional[Applicability] - Applicability restrictions
  • tripwires: List[BlueprintTripwire] - Tripwire configurations
  • checks: List[CanonicalCheck] - Canonical check configurations
  • intervention_policy: InterventionPolicy - Risk-threshold intervention mapping
  • evidence_policy: Optional[EvidencePolicy] - Evidence policy requirements
  • trust_policy: Optional[TrustDebtConfig] - Trust policy configuration

ResolvedBlueprint

Compiled Blueprint artifact consumed by the evaluator after base resolution.

Attributes

  • artifact_type: str - Resolved artifact discriminator (acgp.resolved-blueprint)
  • schema_version: str - Resolved Blueprint schema version
  • source_blueprint: SourceBlueprintRef - Reference to the source Blueprint artifact
  • lineage: List[LineageEntry] - Resolution lineage for the effective policy
  • resolved_at: datetime - When the Blueprint was resolved
  • effective: EffectiveWindow - Validity window for the resolved artifact
  • resolution_metadata: ResolutionMetadata - Resolver/compiler metadata
  • tripwires: List[BlueprintTripwire] - Resolved tripwire configurations
  • checks: List[CanonicalCheck] - Resolved canonical check configurations
  • intervention_policy: InterventionPolicy - Effective intervention policy
  • evidence_policy: Optional[EvidencePolicy] - Effective evidence policy
  • trust_policy: Optional[TrustDebtConfig] - Effective trust policy

BlueprintTripwire

Tripwire configuration within a blueprint.

Spec mapping: - ACGP-4 tripwire semantics - ACGP-3 schema placement for tripwires

Attributes

  • id: str - Unique tripwire identifier
  • when: TripwireCondition - When to evaluate (hook, tool filter)
  • condition: str - Condition expression to evaluate
  • eval_tier: int - Evaluation tier (0 or 1)
  • latency_budget_ms: Optional[int] - Per-tripwire latency budget
  • severity: TripwireSeverity - Tripwire severity level
  • requires_state: bool - Whether tripwire needs stateful storage
  • on_fail: TripwireOnFail - Action when condition fails

TrustDebtConfig

Trust debt tracking configuration.

Spec mapping: - ACGP-3 Section 9 trust debt core

Attributes

  • enabled: bool - Whether trust debt is enabled
  • accumulation: TrustDebtAccumulation - Debt accumulation rates per intervention
  • decay: TrustDebtDecay - Decay configuration
  • thresholds: TrustDebtThresholds - Action thresholds

Enums

InterventionType

class InterventionType(str, Enum):
    OK = "ok"
    NUDGE = "nudge"
    ESCALATE = "escalate"
    BLOCK = "block"
    HALT = "halt"

Note: Values are lowercase per ACGP-1 §3.3. "flag" is NOT a primary decision value — use flags.flagged: true on any primary decision instead.

TripwireSeverity

class TripwireSeverity(str, Enum):
    STANDARD = "standard"
    CRITICAL = "critical"
    SEVERE = "severe"

RiskLevel

class RiskLevel(str, Enum):
    LOW_RISK = "low_risk"
    ELEVATED_RISK = "elevated_risk"
    CRITICAL_RISK = "critical_risk"

Exceptions

Exception Description
ACGPError Base exception for all ACGP errors
PolicyError Invalid policy/blueprint configuration
TripwireViolation Tripwire limit exceeded
BudgetExceeded Performance budget exceeded
AgentHalted Agent has been halted

Message Formats

MessageType

class MessageType(str, Enum):
    TRACE = "TRACE"
    EVAL = "EVAL"
    INTERVENTION = "INTERVENTION"
    HITL = "HITL"
    SESSION_INIT = "SESSION_INIT"
    BUNDLE_UPDATE = "BUNDLE_UPDATE"
    VERSION_NEGOTIATION = "VERSION_NEGOTIATION"
    VERSION_SELECTED = "VERSION_SELECTED"

Cognitive Trace Message

{
    "version": "1.0",
    "trace_id": "trace-12345",
    "agent_id": "agent-abc",
    "timestamp": "2025-11-03T12:00:00Z",
    "reasoning": "User requested password reset for verified email address",
    "action": {
        "name": "send_password_reset_email",
        "parameters": {
            "email": "user@example.com",
            "verification_method": "sms"
        }
    }
}

Evaluation Response Message

{
    "trace_id": "trace-12345",
    "ctq_dimensions": {
        "reasoning_quality": {
            "score": 0.95,
            "weight": 0.25,
            "status": "evaluated",
            "contributors": ["rationale_clarity", "plan_completeness"]
        },
        "knowledge_grounding": {
            "score": 0.92,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["citation_coverage"]
        },
        "ethical_alignment": {
            "score": 0.97,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["fairness_review"]
        },
        "tool_safety": {
            "score": 0.96,
            "weight": 0.20,
            "status": "evaluated",
            "contributors": ["permission_check"]
        },
        "context_awareness": {
            "score": 0.93,
            "weight": 0.15,
            "status": "evaluated",
            "contributors": ["situational_fit"]
        }
    },
    "ctq_score": 0.947,
    "risk_score": 0.053,
    "effective_thresholds": {
        "ok": 0.25,
        "nudge": 0.40,
        "escalate": 0.55
    },
    "tripwires_triggered": []
}

Use the full envelope format from the wire protocol when transmitting this over the network. The payload above reflects the canonical EVAL result shape standardized by ACGP-2.

See full normative message semantics in ACGP-2 Messages & Wire Protocol.

Type Aliases

from acgp import (
    InterventionType,  # Enum with OK, NUDGE, ESCALATE, BLOCK, HALT
    RiskLevel,         # Enum with LOW_RISK, ELEVATED_RISK, CRITICAL_RISK
    TripwireSeverity,  # Enum with STANDARD, CRITICAL, SEVERE
)

Wire Protocol Spec Implementation Guide