ActionGuard
The main entry point. Assembles the evaluation pipeline, audit log, rollback system, and multi-agent trust ledger.Constructor
ActionGuard.default()
Create an instance with sensible defaults. No config file needed — good for quick starts and testing.ActionGuard.from_config()
Create an instance from a YAML config file.guard.protect()
Decorator to protect a function with ActionGuard.Baseline risk level for this action. One of
LOW, MEDIUM, HIGH, CRITICAL.guard.wrap()
Wrap framework-native tools with ActionGuard protection. Auto-detects the framework and routes to the appropriate adapter.guard.evaluate()
Evaluate anActionIntent without executing (dry-run).
guard.evaluate_async()
Async version. Runs the evaluation pipeline in a thread to avoid blocking the event loop.guard.explain()
Run the full evaluation pipeline in dry-run mode and return a rich, human-readable explanation string. Never executes the action.guard.explain_async()
Async version ofexplain().
guard.get_audit_log()
Query the audit log with optional filters.Optional filter criteria. If
None, returns all entries up to the default limit.guard.get_metrics()
Get a snapshot of aggregate metrics.guard.add_exporter()
Register an audit log exporter. Exporters receive everyAuditEntry as it
is written.
guard.register_agent()
Register an agent with a trust level for multi-agent systems.guard.rollback()
Roll back a single action by its ID.guard.rollback_last()
Roll back the last N actions.guard.rollback_task()
Roll back all actions for a task across all agents.guard.serve()
Start the HTTP sidecar server (dashboard + REST API).Requires
pip install "plyra-guard[sidecar]". Raises ImportError if
FastAPI or uvicorn are not installed.Data classes
ActionIntent
The primary data structure that flows through the evaluation pipeline.EvaluatorResult
The output of a single evaluator in the pipeline.AuditEntry
Immutable audit record written for every action evaluated.AuditFilter
Filter criteria for querying the audit log.GuardMetrics
Prometheus-style metrics snapshot.RollbackReport
Summary of a batch rollback operation.
Property:
report.success → True if no failures and at least one rollback.
AgentCall
One hop in a multi-agent delegation chain.Enums
Verdict
Helper methods:
verdict.is_permissive()→TrueforALLOWandWARNverdict.is_blocking()→TrueforBLOCK,ESCALATE, andDEFER
RiskLevel
Helper:
risk_level.base_score() → returns the float value.
TrustLevel
Helper:
trust_level.score() → returns the float value.
Exceptions
All exceptions inherit fromActionGuardError.
Execution exceptions
Policy exceptions
Config exceptions
Budget and rate limit exceptions
Other exceptions
Structured error messages
All blocking exceptions (ExecutionBlockedError, ActionEscalatedError,
RateLimitExceededError, BudgetExceededError, TrustViolationError,
CascadeDepthExceededError, ActionDeferredError) provide three structured fields:
what_happened— clear plain-English descriptionpolicy_triggered— name of the policy or evaluatorhow_to_fix— concrete, actionable steps
Environment variables
Configuration schema
The YAML config file maps to theGuardConfig Pydantic model: