API Reference¶

Complete SDK API documentation.

GovernanceSteward¶

Main class for evaluating agent actions against blueprints.

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 = "minimal",
    enable_warnings: bool = True,
)

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 - conformance_level: "minimal", "standard", or "complete" - enable_warnings: Enable production warnings for Minimal conformance

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.

Methods¶

evaluate()¶

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

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

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

Returns: - InterventionResult with intervention type and message

get_metrics()¶

get_metrics() -> Dict[str, Any]

Get governance metrics including evaluation counts and intervention statistics.

CognitiveTrace¶

Represents agent reasoning and planned action.

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,
    agent_tier: Optional[str] = None,
)

InterventionResult¶

Result of governance evaluation.

Attributes¶

intervention: InterventionType - One of OK, NUDGE, FLAG, 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

Blueprint¶

Governance policy configuration loaded from YAML or dictionary.

Attributes¶

id: str - Unique blueprint identifier (e.g., 'finance/trading@1.0')
version: str - Blueprint version (semantic versioning)
description: str - Blueprint description
inherits: Optional[str] - Parent blueprint ID to inherit from
scope: Optional[BlueprintScope] - Scope restrictions
tripwires: List[BlueprintTripwire] - Tripwire configurations
checks: List[BlueprintCheck] - CTQ check configurations
evidence: Optional[EvidenceRequirements] - Evidence requirements
scoring: Optional[ScoringThresholds] - Scoring thresholds
trust_debt: Optional[TrustDebtConfig] - Trust debt configuration

BlueprintTripwire¶

Tripwire configuration within a blueprint.

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.

Attributes¶

enabled: bool - Whether trust debt is enabled
accumulation: TrustDebtAccumulation - Debt accumulation rates per intervention
decay: TrustDebtDecay - Decay configuration
recovery: Optional[TrustDebtRecovery] - Recovery configuration
thresholds: TrustDebtThresholds - Action thresholds

Decorators¶

@guard¶

Zero-config governance decorator.

from acgp import guard

@guard(tripwires=["spend < 50"], blocked_keywords=["password"])
def process_refund(amount: float, reason: str):
    # Function is automatically governed
    return refund_service.process(amount, reason)

Parameters: - tripwires: List of simple tripwire strings (e.g., ["spend < $50", "no_pii"]) - rules: List of custom rule dictionaries - max_spend: Maximum spend limit (shortcut for spend tripwire) - blocked_keywords: Keywords to block in reasoning - action_name: Name of the action (defaults to function name) - on_deny: Callback function called when action is denied - on_review: Callback function called when action needs review

Enums¶

InterventionType¶

class InterventionType(str, Enum):
    OK = "OK"
    NUDGE = "NUDGE"
    FLAG = "FLAG"
    ESCALATE = "ESCALATE"
    BLOCK = "BLOCK"
    HALT = "HALT"

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

Type Aliases¶

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

Message Formats Examples