ybuild 0.4.0

Python SDK for Y Build Runtime - Cloud Container Execution Platform

Y Build Python SDK

Official Python SDK for Y Build Runtime - a cloud container execution platform.

Installation

pip install ybuild

Quick Start

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

# 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

# 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

# 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

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

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

Error Handling

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

# 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

# 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