Quickstart

from plyra_guard import ActionGuard, RiskLevel

guard = ActionGuard.default()

@guard.protect("file.delete", risk_level=RiskLevel.HIGH)
def delete_file(path: str) -> str:
    import os
    os.remove(path)
    return f"Deleted {path}"

delete_file("/tmp/report.txt")   # Verdict: ALLOW — executes normally
delete_file("/etc/passwd")       # Verdict: BLOCK — ExecutionBlockedError raised

<Note>
  `ExecutionBlockedError` carries three fields that explain exactly what
  happened: `what_happened`, `policy_triggered`, and `how_to_fix`.
  Catch it to handle blocks gracefully in your agent loop.
</Note>

version: "1.0"

global:
  default_verdict: BLOCK

policies:
  - name: block-env-files
    action_types: ["*"]
    condition: '".env" in parameters.get("path", "")'
    verdict: BLOCK
    message: "No .env access"

  - name: block-system-config
    action_types: ["*"]
    condition: 'parameters.get("path", "").startswith("/etc/")'
    verdict: BLOCK
    message: "System config is off-limits"

  - name: allow-tmp
    action_types: ["*"]
    condition: 'parameters.get("path", "").startswith("/tmp/")'
    verdict: ALLOW

  - name: escalate-schema-changes
    action_types: ["*"]
    condition: '"DROP TABLE" in str(parameters)'
    verdict: ESCALATE
    message: "Schema changes require human approval"

guard = ActionGuard.from_config("guard_config.yaml")

safe_tools = guard.wrap([read_file, write_file, delete_file])

pip install "plyra-guard[sidecar]"
plyra-guard serve
# → http://localhost:8765