Metadata-Version: 2.4
Name: kanyun-sandbox
Version: 0.1.0
Summary: Python SDK for Kanyun Sandbox Platform - Control Plane client with integrated Agent access
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.23.0
Requires-Dist: agent-sandbox>=0.0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.20; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"

# Kanyun Sandbox Python SDK

Kanyun Sandbox 平台的 Python SDK，提供 Control Plane 客户端和集成的 Agent 访问能力。

## 安装

```bash
pip install kanyun-sandbox
```

## 快速开始

```python
from kanyun_sandbox import Client

client = Client(
    control_plane_url="https://sandbox.zhenguanyu.com",
    api_key="your-api-key",
)

# 使用 run_session 自动管理 Sandbox 生命周期
with client.run_session(template_name="python", ttl_seconds=300) as session:
    # 执行 Shell 命令
    result = session.agent.shell.exec_command(command="echo hello")
    print(result.data.output)

    # 写入文件
    session.agent.file.write_file(file="/tmp/test.txt", content="Hello!")

    # 读取文件
    read_result = session.agent.file.read_file(file="/tmp/test.txt")
    print(read_result.data.content)
# Sandbox 在 with 块结束时自动销毁
```

## 客户端配置

```python
client = Client(
    control_plane_url="https://sandbox.example.com",  # 必填
    api_key="your-api-key",          # API 认证密钥
    user_id="user-123",              # 用户 ID（X-User-ID header）
    agent_port=8080,                 # Agent 端口（默认 8080）
    use_agent_endpoint=False,        # 优先使用 agent_endpoint 而非 pod_ip
    timeout=60.0,                    # HTTP 请求超时（秒）
)
```

## API

### Sandbox 管理

```python
from kanyun_sandbox import CreateSandboxRequest

# 创建 Sandbox
handle = client.create_sandbox(CreateSandboxRequest(
    template_name="python",
    ttl_seconds=600,
    labels={"env": "test"},
))

# 通过 handle 执行命令
result = handle.agent.shell.exec_command(command="ls -la")

# 延长 TTL
handle.extend(ttl_seconds=300)

# 销毁
handle.destroy()
```

```python
# 获取 Sandbox 信息
info = client.get_sandbox("sandbox-id")

# 列出 Sandbox
response = client.list_sandboxes(label_selector="env=test")
for sb in response.sandboxes:
    print(f"{sb.id}: {sb.phase}")

# 连接已有 Sandbox
handle = client.connect_sandbox("sandbox-id")

# 删除 Sandbox
client.delete_sandbox("sandbox-id")
```

### Template 管理

```python
# 列出所有模板
templates = client.list_templates()
for t in templates.templates:
    print(f"{t.name}: {t.description}")

# 获取指定模板
tmpl = client.get_template("python")
```

### Session（推荐）

```python
# 方式 1: context manager（推荐）
with client.run_session(template_name="python", ttl_seconds=300) as session:
    session.agent.shell.exec_command(command="echo hello")

# 方式 2: 手动管理
session = client.new_session(CreateSandboxRequest(template_name="python"))
try:
    session.agent.shell.exec_command(command="echo hello")
finally:
    session.close()
```

### Agent 能力

通过 `session.agent` 或 `handle.agent` 访问 [agent-sandbox](https://github.com/agent-infra/sandbox/tree/main/sdk/python) 提供的全部能力：

- **Shell**: `agent.shell.exec_command(...)` - 执行 Shell 命令
- **File**: `agent.file.read_file(...)`, `agent.file.write_file(...)`, `agent.file.list_path(...)` - 文件操作
- **Jupyter**: `agent.jupyter` - Jupyter notebook 执行
- **Node.js**: `agent.nodejs` - Node.js 代码执行
- **Browser**: `agent.browser` - 浏览器自动化
- **Code**: `agent.code` - 统一代码执行

## 与 Go SDK 对照

| Go SDK | Python SDK |
|--------|------------|
| `kanyun.NewClient(opts...)` | `Client(control_plane_url=..., api_key=...)` |
| `client.CreateSandbox(ctx, req)` | `client.create_sandbox(req)` |
| `client.RunSession(ctx, req, fn)` | `with client.run_session(...) as session:` |
| `handle.Agent().Shell.ExecCommand(...)` | `handle.agent.shell.exec_command(...)` |
| `handle.Extend(ctx, ttl)` | `handle.extend(ttl)` |
| `handle.Destroy(ctx)` | `handle.destroy()` |
| `session.Close(ctx)` | `session.close()` |

## 依赖

- Python 3.9+
- [httpx](https://www.python-httpx.org/) - HTTP 客户端
- [agent-sandbox](https://pypi.org/project/agent-sandbox/) - Agent 端 SDK
