Skip to main content
Version: 0.3.0
Last Verified: 2025-01-27
Package: hopx-ai on PyPI

​
Overview

The Python SDK provides data models for all API responses and objects. These models provide type safety, convenience methods, and clear documentation of data structures.

​
Import

from hopx_ai import (
    SandboxInfo,
    Template as SandboxTemplate,
    ExecutionResult,
    CommandResult,
    FileInfo,
    RichOutput,
    VNCInfo,
    WindowInfo,
    RecordingInfo,
    DisplayInfo
)

​
Core Models

​
SandboxInfo

Sandbox information model. Fields:
  • sandbox_id (str): Unique sandbox identifier
  • template_id (str): Template ID used to create sandbox
  • template_name (str): Template name
  • organization_id (str): Organization ID
  • node_id (str): Node ID
  • region (str): Deployment region
  • status (str): Sandbox status ("running", "stopped", "paused", "creating")
  • public_host (str): Public hostname
  • resources (Resources): Resource specifications
  • started_at (datetime): Start timestamp
  • end_at (datetime, optional): End timestamp
  • created_at (datetime): Creation timestamp
Example: 
info = sandbox.get_info()
print(f"ID: {info.sandbox_id}")
print(f"Status: {info.status}")
print(f"Host: {info.public_host}")

​
Template

Template information model. Fields:
  • id (str): Template ID
  • name (str): Template name
  • display_name (str): Display name
  • description (str): Template description
  • category (str): Template category
  • language (str): Primary language
  • icon (str, optional): Icon URL
  • default_resources (TemplateResources): Default resource specifications
  • min_resources (TemplateResources): Minimum resources
  • max_resources (TemplateResources): Maximum resources
  • features (List[str]): Available features
  • tags (List[str]): Template tags
  • popularity_score (float): Popularity score
  • docs_url (str, optional): Documentation URL
  • is_active (bool): Whether template is active
  • status (str): Template status
Example: 
template = Sandbox.get_template("code-interpreter")
print(f"Name: {template.name}")
print(f"Resources: {template.default_resources.vcpu} vCPU")

​
ExecutionResult

Result of code execution. Fields:
  • success (bool): Whether execution succeeded
  • stdout (str): Standard output
  • stderr (str): Standard error
  • exit_code (int): Exit code (0 = success)
  • execution_time (float): Execution time in seconds
  • rich_outputs (List[RichOutput]): Rich outputs (plots, DataFrames, etc.)
Properties:
  • rich_count (int): Number of rich outputs
Example: 
result = sandbox.run_code("print('Hello')")
print(result.stdout)
print(f"Success: {result.success}")
print(f"Rich outputs: {result.rich_count}")

​
CommandResult

Result of command execution. Fields:
  • stdout (str): Standard output
  • stderr (str): Standard error
  • exit_code (int): Exit code
  • execution_time (float): Execution time in seconds
Properties:
  • success (bool): Whether command succeeded (exit_code == 0)
Example: 
result = sandbox.commands.run("ls -la")
print(result.stdout)
print(f"Success: {result.success}")

​
FileInfo

File or directory information. Fields:
  • name (str): File or directory name
  • path (str): Full path
  • size (int): Size in bytes
  • is_directory (bool): Whether it’s a directory
  • permissions (str): File permissions
  • modified_time (datetime): Last modification time
Properties:
  • is_file (bool): Whether it’s a file
  • is_dir (bool): Whether it’s a directory
  • size_kb (float): Size in kilobytes
  • size_mb (float): Size in megabytes
Example: 
items = sandbox.files.list("/workspace")
for item in items:
    if item.is_directory:
        print(f"Directory: {item.name}")
    else:
        print(f"File: {item.name} ({item.size_kb:.2f} KB)")

​
RichOutput

Rich output from code execution (plots, DataFrames, etc.). Fields:
  • type (str): Output type ("plot", "dataframe", "html", etc.)
  • data (str or bytes): Output data
  • metadata (Dict[str, Any]): Additional metadata
  • timestamp (datetime): Output timestamp
Example: 
result = sandbox.run_code("import matplotlib.pyplot as plt; plt.plot([1,2,3]); plt.savefig('/tmp/plot.png')")
for output in result.rich_outputs:
    if output.type == "plot":
        print(f"Plot generated at {output.timestamp}")

​
Desktop Models

​
VNCInfo

VNC server information. Fields:
  • running (bool): Whether VNC is running
  • display (int): Display number
  • port (int): VNC port
  • url (str): VNC URL
  • password (str): VNC password

​
WindowInfo

Window information. Fields:
  • id (str): Window ID
  • title (str): Window title
  • x (int): X coordinate
  • y (int): Y coordinate
  • width (int): Window width
  • height (int): Window height
  • desktop (int): Desktop number
  • pid (int): Process ID

​
RecordingInfo

Screen recording information. Fields:
  • recording_id (str): Recording ID
  • status (str): Recording status
  • fps (int): Frames per second
  • format (str): Video format
  • duration (float): Duration in seconds
  • file_size (int): File size in bytes
Properties:
  • is_recording (bool): Whether recording is active
  • is_ready (bool): Whether recording is ready

​
DisplayInfo

Display information. Fields:
  • width (int): Display width
  • height (int): Display height
  • depth (int): Color depth
Properties:
  • resolution (Tuple[int, int]): Resolution tuple

​
Resource Models

​
Resources

Resource specifications. Fields:
  • vcpu (int): Number of vCPUs
  • memory_mb (int): Memory in megabytes
  • disk_mb (int): Disk space in megabytes

​
TemplateResources

Template resource specifications. Fields:
  • vcpu (int): Number of vCPUs
  • memory_mb (int): Memory in megabytes
  • disk_gb (int): Disk space in gigabytes
  • Errors - Error classes and exception handling
  • Sandbox - Use models with sandbox operations

​
See Also

​
Next Steps

Now that you understand data models, explore: