# VasperaGuard Python SDK

The safety & governance layer for AI agents.

## Installation

```bash
pip install vaspera-guard
```

## Quick Start

```python
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

```python
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

```python
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

```python
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

```python
# 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](https://vasperamemory.com)** - Persistent memory for AI agents
- **[VasperaMesh](https://vasperamesh.com)** - Multi-agent orchestration
- **[VasperaShield](https://vasperashield.com)** - Security scanning
- **[VasperaProject](https://vasperaproject.com)** - 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
