ybuild 0.2.0
Python SDK for Y Build Runtime - Cloud Container Execution Platform
Requires Python: >=3.8
Keywords: cloud, container, docker, execution, runtime, sandbox, ybuild

# Y Build Python SDK

Official Python SDK for [Y Build Runtime](https://github.com/baoyuanliu/ybuild-runtime) - a cloud container execution platform.

## Installation

```bash
pip install ybuild
```

## Quick Start

```python
from ybuild import YBuildClient

# Initialize client
client = YBuildClient(
    api_url="https://api.ybuild.dev",
    api_key="ybld_your_api_key"
)

# Create a container
container = client.create_container(thread_id="my-session")

# Wait for container to be ready
container.wait_until_running()

# Execute commands
result = container.exec("python -c 'print(1+1)'")
print(result.stdout)  # "2"

# File operations
container.write_file("/workspace/hello.py", "print('Hello, World!')")
result = container.exec("python /workspace/hello.py")
print(result.stdout)  # "Hello, World!"

# Read files
content = container.read_file("/workspace/hello.py")
print(content)

# Stop when done
container.stop()
```

## Features

### Container Management

```python
# Create with custom resources
container = client.create_container(
    thread_id="my-session",
    cpu_limit=2.0,           # 2 CPU cores
    memory_limit=8*1024**3,  # 8GB RAM
    timeout_seconds=3600,    # 1 hour idle timeout
)

# Get existing container
container = client.get_container("container-id")

# Or by thread ID
container = client.get_container_by_thread("my-session")

# List containers
containers = client.list_containers(status="running")
```

### Command Execution

```python
# Basic execution
result = container.exec("ls -la")
print(result.stdout)
print(result.exit_code)

# With timeout and working directory
result = container.exec(
    "npm install",
    timeout=120,
    workdir="/workspace/myproject"
)

# Python code
result = container.exec_python("""
import json
data = {"hello": "world"}
print(json.dumps(data))
""")

# Node.js code
result = container.exec_node("""
const x = 1 + 1;
console.log(x);
""")

# Check success
if result.success:
    print("Command succeeded!")
else:
    print(f"Failed with exit code {result.exit_code}")
    print(result.stderr)
```

### File Operations

```python
# Write file
container.write_file("/workspace/data.json", '{"key": "value"}')

# Read file
content = container.read_file("/workspace/data.json")

# List files
files = container.list_files("/workspace")
for f in files:
    print(f"{f.name} ({f.size} bytes)")

# Delete file
container.delete_file("/workspace/data.json")

# Check if exists
if container.file_exists("/workspace/script.py"):
    container.run_python_file("/workspace/script.py")
```

### Package Installation

```python
# Install Python packages
container.install_pip("requests", "pandas", "numpy")

# Install npm packages
container.install_npm("express", "lodash")
```

### Error Handling

```python
from ybuild import (
    YBuildError,
    AuthenticationError,
    ContainerNotFoundError,
    QuotaExceededError,
    RateLimitError,
)

try:
    container = client.create_container(thread_id="test")
except AuthenticationError:
    print("Invalid API key")
except QuotaExceededError:
    print("Container quota exceeded")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except YBuildError as e:
    print(f"API error: {e}")
```

### Service Discovery

```python
# Check service info
info = client.discover()
print(f"Service: {info.service}")
print(f"Version: {info.version}")
print(f"API Version: {info.api_version}")

# Health check
health = client.health()
print(health["status"])  # "healthy"
```

## Context Manager

```python
# Client auto-closes when done
with YBuildClient(api_url="...", api_key="...") as client:
    container = client.create_container(thread_id="test")
    result = container.exec("echo hello")
    container.stop()
```

## Configuration

| Parameter | Description | Default |
|-----------|-------------|---------|
| `api_url` | API base URL | Required |
| `api_key` | API key (ybld_xxx) | None |
| `timeout` | Request timeout (seconds) | 30 |
| `max_retries` | Retry count for failures | 3 |

## Container Options

| Option | Description | Default |
|--------|-------------|---------|
| `thread_id` | Unique session identifier | Required |
| `cpu_limit` | CPU cores | 1.0 |
| `memory_limit` | Memory in bytes | 4GB |
| `storage_limit` | Storage in bytes | 20GB |
| `timeout_seconds` | Idle timeout | 7200 (2h) |
| `image` | Container image | Default |

## License

MIT