# Ezop Python SDK

Ezop tracks the lifecycle of your AI agents — registrations, versions, and runs — so you have full observability across every deployment.

## Installation

```bash
pip install ezop
```

## Configuration

Set your API key before using the SDK:

```bash
export EZOP_API_KEY=your-ezop-api-key-here
export EZOP_API_URL=https://api.ezop.ai   # optional, this is the default
```

## Quick start

```python
from ezop import Agent

# Register your agent at startup (safe to call on every deploy — idempotent)
agent = Agent.init(
    name="customer-support-bot",
    owner="growth-team",
    version="v0.3",
    runtime="langchain",
    description="Handles tier-1 customer support tickets",
    default_permissions=["read:tickets"],
    permissions=["read:tickets", "write:replies"],
    changelog="Switched to new retrieval pipeline",
)

# Track a run
agent.start_run()

try:
    result = your_agent_logic(user_input)
    agent.end_run(
        status="completed",
        total_tokens=result.usage.total_tokens,
        total_cost=result.cost,
        metadata={"user_id": user_id},
    )
except Exception as e:
    agent.end_run(status="failed", metadata={"error": str(e)})
    raise
```

## API reference

### `Agent.init()`

Registers the agent and its current version with the Ezop platform. On subsequent calls with the same `name` + `owner`, the agent record is updated in place — safe to call on every startup.

| Parameter | Required | Description |
|---|---|---|
| `name` | yes | Agent name |
| `owner` | yes | Team or user that owns the agent |
| `version` | yes | Version string for this deployment (e.g. `"v0.3"`) |
| `runtime` | yes | Runtime framework (e.g. `"langchain"`, `"langchain"`, `"python"`) |
| `description` | no | Human-readable description of the agent |
| `default_permissions` | no | Default permission scopes for the agent |
| `permissions` | no | Permission scopes for this specific version |
| `changelog` | no | Release notes for this version |

### `agent.start_run()`

Creates a new run record with status `running`. Call this at the start of each agent invocation.

### `agent.end_run()`

Closes the current run. Only provided fields are written.

| Parameter | Default | Description |
|---|---|---|
| `status` | `"completed"` | Final run status (`"completed"`, `"failed"`, etc.) |
| `total_tokens` | `None` | Total tokens consumed |
| `total_cost` | `None` | Total cost in USD |
| `metadata` | `None` | Arbitrary JSON metadata |

## Logging

The SDK uses Python's standard `logging` module under the `ezop` namespace. To enable logs in your application:

```python
import logging
logging.getLogger("ezop").setLevel(logging.DEBUG)
```
