VasperaGuard Python SDK

The safety & governance layer for AI agents.

Installation

pip install vaspera-guard

Quick Start

from vaspera_guard import Guard

# Initialize with API key
guard = Guard(api_key="vg_...")
# Or set VASPERA_GUARD_API_KEY environment variable

# Check if a command is safe
result = guard.check("rm -rf /tmp/cache")

if result.allowed:
    # Safe to execute
    subprocess.run(command, shell=True)
elif result.requires_approval:
    # Request human approval
    approval = guard.request_approval(
        result.check_id,
        command,
        channel="slack",
        slack_channel="#devops"
    )
    print(f"Approval requested: {approval.approve_url}")
else:
    # Command blocked
    print(f"Blocked: {result.reason}")
    print(f"Suggestions: {result.suggestions}")

Usage with AI Agents

from vaspera_guard import Guard, AgentContext

guard = Guard(
    api_key="vg_...",
    agent_id="my-coding-agent",
    environment="production"
)

async def agent_execute(command: str):
    """Execute a command with VasperaGuard protection."""

    # Check safety before execution
    result = guard.check(
        command,
        context=AgentContext(
            environment="production",
            project="backend-api",
            working_directory="/app"
        )
    )

    if result.blocked:
        return f"Command blocked: {result.reason}"

    if result.requires_approval:
        approval = guard.request_approval(
            result.check_id,
            command,
            channel="slack",
            slack_channel="#agent-approvals",
            reason="Agent needs to run this for deployment"
        )
        # Wait for approval (max 5 minutes)
        final = guard.wait_for_approval(approval.approval_id, timeout=300)
        if not final.is_approved:
            return "Approval denied"

    # Execute the command
    return subprocess.run(command, shell=True, capture_output=True)

Check and Execute Pattern

from vaspera_guard import Guard

guard = Guard()

def run_cmd(cmd):
    return subprocess.run(cmd, shell=True, capture_output=True)

# Automatically check and execute
result = guard.check_and_execute(
    "ls -la",
    executor=run_cmd,
    on_blocked=lambda r: print(f"Blocked: {r.reason}"),
    on_approval_required=lambda r: print(f"Needs approval: {r.approval_url}")
)

Custom Policies

from vaspera_guard import Guard, PolicyRule

guard = Guard()

# Create a policy for production
policy = guard.create_policy(
    name="production-safety",
    description="Strict safety rules for production",
    rules=[
        PolicyRule(pattern="DROP TABLE", action="block"),
        PolicyRule(pattern="rm -rf", action="require_approval"),
        PolicyRule(pattern="chmod 777", action="warn"),
    ],
    environments=["production"]
)

# Use the policy
result = guard.check("DROP TABLE users", policy_id=policy.policy_id)
# result.blocked == True

Audit Trail

# Get audit log
entries = guard.get_audit_log(
    agent_id="my-agent",
    risk_level="high",
    limit=50
)

for entry in entries:
    print(f"{entry.timestamp}: {entry.command} -> {entry.check_result}")

Part of the Vaspera Platform

VasperaGuard works best with the full Vaspera ecosystem:

• VasperaMemory - Persistent memory for AI agents
• VasperaMesh - Multi-agent orchestration
• VasperaShield - Security scanning
• VasperaProject - Spec-to-code tracking

API Reference

Guard

• check(command, agent_id, context, policy_id) - Check command safety
• check_and_execute(command, executor, ...) - Check and execute if safe
• request_approval(check_id, command, ...) - Request human approval
• get_approval_status(approval_id) - Check approval status
• wait_for_approval(approval_id, timeout) - Wait for approval decision
• create_policy(name, rules, ...) - Create custom policy
• list_policies() - List all policies
• get_audit_log(...) - Get audit trail
• get_stats() - Get usage statistics

Models

• CheckResult - Result from safety check
• ApprovalResult - Result from approval request
• AgentContext - Context about the agent
• Policy - Safety policy
• PolicyRule - Rule in a policy
• AuditEntry - Audit log entry

License

MIT