# Python SDK

The official Python SDK provides access to the Chaser API for session management, workspaces, command execution, file operations, browser CDP, accounts, billing, webhooks, audit, and jobs.

## Install

```bash
pip install chaser-sdk

# Optional: CDP WebSocket support
pip install "chaser-sdk[cdp]"
```

## Create a client

```python
from chaser_sdk import ChaserClient

client = ChaserClient(api_key="sk_...", account="personal")
```

## Sessions

```python
# Create a sandbox session
session = client.sessions.create({
    "session_type": "sandbox",
    "workspace": "my-project",
})

client.sessions.wait_until_ready(session["id"])

# Create a browser session
browser = client.sessions.create({
    "session_type": "browser",
    "ephemeral": True,
})
```

## Command execution

```python
# Run in an existing session
result = client.exec.in_session(session["id"], {
    "command": "npm ci && npm test",
    "cwd": "/workspace",
})

# Auto-provisioned ephemeral sandbox
result = client.exec.run({
    "ephemeral": True,
    "image": "node:20-bookworm",
    "command": "python3 -c 'print(42)'",
})
```

## Workspaces

```python
workspace = client.workspaces.create({
    "name": "frontend-app",
    "session_type": "sandbox",
    "image": "ghcr.io/example/dev:latest",
})
```

## Files

```python
client.files.upload_text(session["id"], "/workspace/hello.txt", "hello")
text = client.files.download_text(session["id"], "/workspace/hello.txt")
```

## Browser CDP

```python
# Get the WebSocket URL
ws_url = client.browser.cdp_websocket_url(browser["id"])

# With the cdp extra: open a connection
cdp = client.browser.connect(browser["id"])
print(cdp.send("Browser.getVersion"))
cdp.close()
```

## Organization context

```python
org_client = client.with_account("Acme Engineering")
workspaces = org_client.workspaces.list()
```

## Notes

- The SDK is stdlib-first -- basic usage requires no extra dependencies
- `pip install "chaser-sdk[cdp]"` adds WebSocket CDP support
- The SDK covers the core Chaser API surface. It does not include CHASM assistant management.