Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

Added reference documentation for: libs/python/pylume/pylume/models.py

Andrei Onel8b2dd7bb7bcb
diff --git a/libs/python/pylume/pylume/models.py b/libs/python/pylume/pylume/models.py
index 664065ad14..cd2ddb2ba7 100644
--- a/libs/python/pylume/pylume/models.py
+++ b/libs/python/pylume/pylume/models.py
@@ -3,6 +3,12 @@ import re
from pydantic import BaseModel, Field, computed_field, validator, ConfigDict, RootModel
class DiskInfo(BaseModel):
+ """Information about disk storage allocation.
+
+ Attributes:
+ total: Total disk space in bytes
+ allocated: Currently allocated disk space in bytes
+ """
total: int
allocated: int
@@ -10,6 +16,15 @@ class VMConfig(BaseModel):
"""Configuration for creating a new VM.
Note: Memory and disk sizes should be specified with units (e.g., "4GB", "64GB")
+
+ Attributes:
+ name: Name of the virtual machine
+ os: Operating system type, either "macOS" or "linux"
+ cpu: Number of CPU cores to allocate
+ memory: Amount of memory to allocate with units
+ disk_size: Size of the disk to create with units
+ display: Display resolution in format "widthxheight"
+ ipsw: IPSW path or 'latest' for macOS VMs, None for other OS types
"""
name: str
os: Literal["macOS", "linux"] = "macOS"
@@ -23,7 +38,12 @@ class VMConfig(BaseModel):
populate_by_alias = True
class SharedDirectory(BaseModel):
- """Configuration for a shared directory."""
+ """Configuration for a shared directory.
+
+ Attributes:
+ host_path: Path to the directory on the host system
+ read_only: Whether the directory should be mounted as read-only
+ """
host_path: str = Field(..., alias="hostPath") # Allow host_path but serialize as hostPath
read_only: bool = False
@@ -50,6 +70,16 @@ class VMRunOpts(BaseModel):
)
def model_dump(self, **kwargs):
+ """Export model data with proper field name conversion.
+
+ Converts shared directory fields to match API expectations when using aliases.
+
+ Args:
+ **kwargs: Keyword arguments passed to parent model_dump method
+
+ Returns:
+ dict: Model data with properly formatted field names
+ """
data = super().model_dump(**kwargs)
# Convert shared directory fields to match API expectations
if self.shared_directories and "by_alias" in kwargs and kwargs["by_alias"]:
@@ -65,6 +95,18 @@ class VMRunOpts(BaseModel):
return data
class VMStatus(BaseModel):
+ """Status information for a virtual machine.
+
+ Attributes:
+ name: Name of the virtual machine
+ status: Current status of the VM
+ os: Operating system type
+ cpu_count: Number of CPU cores allocated
+ memory_size: Amount of memory allocated in bytes
+ disk_size: Disk storage information
+ vnc_url: URL for VNC connection if available
+ ip_address: IP address of the VM if available
+ """
name: str
status: str
os: Literal["macOS", "linux"]
@@ -80,38 +122,79 @@ class VMStatus(BaseModel):
@computed_field
@property
def state(self) -> str:
+ """Get the current state of the VM.
+
+ Returns:
+ str: Current VM status
+ """
return self.status
@computed_field
@property
def cpu(self) -> int:
+ """Get the number of CPU cores.
+
+ Returns:
+ int: Number of CPU cores allocated to the VM
+ """
return self.cpu_count
@computed_field
@property
def memory(self) -> str:
+ """Get memory allocation in human-readable format.
+
+ Returns:
+ str: Memory size formatted as "{size}GB"
+ """
# Convert bytes to GB
gb = self.memory_size / (1024 * 1024 * 1024)
return f"{int(gb)}GB"
class VMUpdateOpts(BaseModel):
+ """Options for updating VM configuration.
+
+ Attributes:
+ cpu: Number of CPU cores to update to
+ memory: Amount of memory to update to with units
+ disk_size: Size of disk to update to with units
+ """
cpu: Optional[int] = None
memory: Optional[str] = None
disk_size: Optional[str] = None
class ImageRef(BaseModel):
- """Reference to a VM image."""
+ """Reference to a VM image.
+
+ Attributes:
+ image: Name of the image
+ tag: Tag version of the image
+ registry: Registry hostname where image is stored
+ organization: Organization or namespace in the registry
+ """
image: str
tag: str = "latest"
registry: Optional[str] = "ghcr.io"
organization: Optional[str] = "trycua"
def model_dump(self, **kwargs):
- """Override model_dump to return just the image:tag format."""
+ """Override model_dump to return just the image:tag format.
+
+ Args:
+ **kwargs: Keyword arguments (ignored)
+
+ Returns:
+ str: Image reference in "image:tag" format
+ """
return f"{self.image}:{self.tag}"
class CloneSpec(BaseModel):
- """Specification for cloning a VM."""
+ """Specification for cloning a VM.
+
+ Attributes:
+ name: Name of the source VM to clone
+ new_name: Name for the new cloned VM
+ """
name: str
new_name: str = Field(alias="newName")
@@ -119,18 +202,44 @@ class CloneSpec(BaseModel):
populate_by_alias = True
class ImageInfo(BaseModel):
- """Model for individual image information."""
+ """Model for individual image information.
+
+ Attributes:
+ imageId: Unique identifier for the image
+ """
imageId: str
class ImageList(RootModel):
- """Response model for the images endpoint."""
+ """Response model for the images endpoint.
+
+ A list-like container for ImageInfo objects that provides
+ iteration and indexing capabilities.
+ """
root: List[ImageInfo]
def __iter__(self):
+ """Iterate over the image list.
+
+ Returns:
+ Iterator over ImageInfo objects
+ """
return iter(self.root)
def __getitem__(self, item):
+ """Get an item from the image list by index.
+
+ Args:
+ item: Index or slice to retrieve
+
+ Returns:
+ ImageInfo or list of ImageInfo objects
+ """
return self.root[item]
def __len__(self):
- return len(self.root)
\ No newline at end of file
+ """Get the number of images in the list.
+
+ Returns:
+ int: Number of images in the list
+ """
+ return len(self.root)
\ No newline at end of file