Metadata-Version: 2.4
Name: agentguard-py
Version: 0.1.0
Summary: Monitor and protect yourself with AI agent budget controls, approval workflows, and anomaly detection.
Author-email: AgentGuard <abhirsu@gmail.com>
License: MIT
Project-URL: Homepage, https://agent-guard.io
Project-URL: Dashboard, https://app.agent-guard.io
Project-URL: Repository, https://github.com/alexhrsu/agentguard
Keywords: agentguard,ai,agents,monitoring,logging,llm,openai,anthropic,budget,approval,safety
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AgentGuard Python SDK

> Monitor and protect yourself with AI agent budget controls, approval workflows, and anomaly detection.

[![PyPI version](https://img.shields.io/pypi/v/agentguard.svg)](https://pypi.org/project/agentguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

AgentGuard sits between your AI agent and its actions. Every action is validated before it runs, checking budgets, rate limits, and approval thresholds in real-time.

## Install

```bash
pip install agentguard
```

## Quick Start

```python
from agentguard import AgentGuard

guard = AgentGuard(api_key="ag_your_api_key")  # Get this from app.agent-guard.io

# Wrap any function for automatic protection
chat = guard.wrap(
    my_chat_function,
    action="openai_chat",
    provider="openai",
    model="gpt-4",
    estimated_cost=0.05,
    get_cost=lambda r: r.usage.total_cost,
)

# This automatically:
# ✓ Checks if agent is active
# ✓ Checks budget limits
# ✓ Checks approval thresholds
# ✓ Runs your function (only if allowed)
# ✓ Logs the result
result = chat("Hello!")
```

## Decorator Style

```python
@guard.protect(action="openai_chat", estimated_cost=0.05)
def chat(prompt):
    return openai.chat(prompt=prompt)

result = chat("Hello!")
```

## Core Methods

### `guard.check(action, estimated_cost)` — Pre-action validation

```python
result = guard.check("openai_chat", estimated_cost=0.05)

if result.allowed:
    response = openai.chat(prompt="Hello")
else:
    print(f"Blocked: {result.message}")
```

### `guard.log(action, ...)` — Log an action

```python
guard.log(
    "api_call",
    provider="openai",
    model="gpt-4",
    cost=0.05,
    status="SUCCESS",
    input_tokens=10,
    output_tokens=25,
)
```

### `guard.track(action)` — Track duration

```python
done = guard.track("openai_chat", provider="openai")

result = openai.chat(prompt="Hello")

done(cost=0.05, response=result)
# Duration is calculated automatically
```

## Budget Management

```python
# Get current budget status
budget = guard.get_budget()
print(f"Spent: ${budget.budget_spent} / ${budget.budget_limit}")

# Check if a specific cost is within budget
check = guard.check_budget(0.50)
if not check.allowed:
    print("Would exceed budget")

# Raise if over budget
guard.ensure_budget(0.50)  # raises BudgetExceededError if over
```

## Approval Workflows

```python
# Request approval for a high-cost action
approval = guard.request_approval(
    "send_bulk_email",
    description="Send marketing email to 10,000 users",
    estimated_cost=45.00,
)

# Wait for human decision (polls every 5 seconds)
try:
    decided = guard.wait_for_approval(approval.id, timeout=3600)
    print("Approved! Proceeding...")
except AgentGuardError:
    print("Rejected or expired")
```

## Error Handling

```python
from agentguard import (
    AgentGuardError,       # Base error
    AgentPausedError,      # Agent is paused
    AgentBlockedError,     # Agent is blocked (kill switch)
    BudgetExceededError,   # Budget limit hit
    ApprovalRequiredError, # Needs human approval
)

try:
    result = chat("Hello!")
except AgentPausedError:
    print("Agent paused — stopping gracefully")
except BudgetExceededError:
    print("Budget exceeded — waiting for reset")
except ApprovalRequiredError as e:
    print(f"Approval needed: {e.approval_id}")
```

## Configuration

```python
guard = AgentGuard(
    api_key="ag_your_api_key",                # Required
    base_url="https://api.agent-guard.io",    # Optional
    timeout=10,                                # Optional: seconds (default: 10)
    debug=False,                               # Optional: debug logging (default: False)
)
```

## Dashboard

Manage your agents, view logs, approve actions, and monitor budgets at **[app.agent-guard.io](https://app.agent-guard.io)**

## Links

- [Website](https://agent-guard.io)
- [Dashboard](https://app.agent-guard.io)
- [GitHub](https://github.com/alexhrsu/agentguard)
- [JS/TypeScript SDK](https://www.npmjs.com/package/agentguard-js)

## License

MIT
