humalab 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

humalab/__init__.py

@@ -1,3 +1,17 @@
+"""HumaLab SDK - Python library for robotics and embodied AI experimentation.
+
+The HumaLab SDK provides tools for managing scenarios, runs, episodes, and metrics
+for robotics experiments and simulations. It supports probabilistic scenario generation,
+metric tracking, and integration with the HumaLab platform.
+
+Main components:
+- init: Context manager for creating and managing runs
+- Run: Represents a complete experimental run
+- Episode: Represents a single episode within a run
+- Scenario: Manages scenario configurations with distributions
+- Metrics: Base class for tracking various metric types
+"""
+
 from humalab.humalab import init, finish, login
 from humalab import assets
 from humalab import metrics

humalab/assets/__init__.py

@@ -1,3 +1,9 @@
+"""Asset management for resources like URDF files, meshes, and media.
+
+This module provides functionality for downloading and listing versioned resources
+from HumaLab, including URDF robot descriptions, meshes, videos, and other data files.
+"""
+
 from .resource_operator import download, list_resources
 from .files import ResourceFile, URDFFile
 

humalab/assets/files/resource_file.py

@@ -4,6 +4,11 @@ from enum import Enum
 from humalab.constants import DEFAULT_PROJECT
 
 class ResourceType(Enum):
+    """Enumeration of supported resource file types.
+
+    Supported types include URDF, MJCF, USD formats for robot descriptions,
+    MESH for 3D models, VIDEO and IMAGE for media files, and DATA for generic data.
+    """
     URDF = "urdf"
     MJCF = "mjcf"
     USD = "usd"
@@ -15,6 +20,20 @@ class ResourceType(Enum):
 
 
 class ResourceFile:
+    """Represents a resource file stored in HumaLab.
+
+    Resource files are versioned assets that can be downloaded and used in runs.
+    They include robot descriptions, meshes, media files, and other data.
+
+    Attributes:
+        project (str): The project name this resource belongs to.
+        name (str): The resource name.
+        version (int): The version number of this resource.
+        filename (str): The local filesystem path to the resource file.
+        resource_type (ResourceType): The type of resource.
+        created_at (datetime | None): When the resource was created.
+        description (str | None): Optional description of the resource.
+    """
     def __init__(self, 
                  name: str, 
                  version: int, 
@@ -33,35 +52,80 @@ class ResourceFile:
 
     @property
     def project(self) -> str:
+        """The project name this resource belongs to.
+
+        Returns:
+            str: The project name.
+        """
         return self._project
-    
+
     @property
     def name(self) -> str:
+        """The resource name.
+
+        Returns:
+            str: The resource name.
+        """
         return self._name
-    
+
     @property
     def version(self) -> int:
+        """The version number of this resource.
+
+        Returns:
+            int: The version number.
+        """
         return self._version
-    
+
     @property
     def filename(self) -> str:
+        """The local filesystem path to the resource file.
+
+        Returns:
+            str: The file path.
+        """
         return self._filename
-    
+
     @property
     def resource_type(self) -> ResourceType:
+        """The type of resource.
+
+        Returns:
+            ResourceType: The resource type.
+        """
         return self._resource_type
 
     @property
     def created_at(self) -> datetime | None:
+        """When the resource was created.
+
+        Returns:
+            datetime | None: The creation timestamp, or None if not available.
+        """
         return self._created_at
 
     @property
     def description(self) -> str | None:
+        """Optional description of the resource.
+
+        Returns:
+            str | None: The description, or None if not provided.
+        """
         return self._description
-    
+
     def __repr__(self) -> str:
+        """String representation of the resource file.
+
+        Returns:
+            str: String representation with all attributes.
+        """
         return f"ResourceFile(project={self._project}, name={self._name}, version={self._version}, filename={self._filename}, resource_type={self._resource_type}, description={self._description}, created_at={self._created_at})"
-    
+
     def __str__(self) -> str:
+        """String representation of the resource file.
+
+        Returns:
+            str: Same as __repr__.
+        """
         return self.__repr__()
 

humalab/assets/files/urdf_file.py

@@ -8,6 +8,16 @@ from humalab.constants import DEFAULT_PROJECT
 
 
 class URDFFile(ResourceFile):
+    """Represents a URDF (Unified Robot Description Format) file resource.
+
+    URDF files describe robot kinematics and geometry. This class handles
+    automatic extraction of compressed URDF archives and locates the main
+    URDF file within the extracted contents.
+
+    Attributes:
+        urdf_filename (str | None): Path to the main URDF file.
+        root_path (str): Root directory containing the extracted URDF and assets.
+    """
     def __init__(self, 
                  name: str, 
                  version: int,
@@ -28,6 +38,11 @@ class URDFFile(ResourceFile):
         self._urdf_filename = os.path.join(self._urdf_filename, self._urdf_filename)
         
     def _extract(self):
+        """Extract the URDF archive and locate the main URDF file.
+
+        Returns:
+            tuple[str, str]: (urdf_filename, root_path)
+        """
         working_path = os.path.dirname(self.filename)
         if os.path.exists(self.filename):
             _, ext = os.path.splitext(self.filename)
@@ -44,6 +59,15 @@ class URDFFile(ResourceFile):
         return local_filename, working_path
 
     def search_resource_file(self, resource_filename: str | None, working_path: str) -> str | None:
+        """Search for a URDF file in the working directory.
+
+        Args:
+            resource_filename (str | None): Optional specific filename to search for.
+            working_path (str): Directory to search within.
+
+        Returns:
+            str | None: Path to the found URDF file, or None if not found.
+        """
         found_filename = None
         if resource_filename:
             search_path = os.path.join(working_path, "**")
@@ -62,8 +86,18 @@ class URDFFile(ResourceFile):
 
     @property
     def urdf_filename(self) -> str | None:
+        """Path to the main URDF file.
+
+        Returns:
+            str | None: The URDF file path.
+        """
         return self._urdf_filename
-    
+
     @property
     def root_path(self) -> str:
+        """Root directory containing the extracted URDF and assets.
+
+        Returns:
+            str: The root path.
+        """
         return self._root_path

humalab/assets/resource_operator.py

@@ -8,23 +8,56 @@ from typing import Any, Optional
 
         
 def _asset_dir(humalab_config: HumalabConfig, name: str, version: int) -> str:
+    """Get the local directory path for a specific asset version.
+
+    Args:
+        humalab_config (HumalabConfig): Configuration containing workspace path.
+        name (str): Asset name.
+        version (int): Asset version.
+
+    Returns:
+        str: Path to the asset directory.
+    """
     return os.path.join(humalab_config.workspace_path, "assets", name, f"{version}")
 
 def _create_asset_dir(humalab_config: HumalabConfig, name: str, version: int) -> bool:
+    """Create the local directory for an asset if it doesn't exist.
+
+    Args:
+        humalab_config (HumalabConfig): Configuration containing workspace path.
+        name (str): Asset name.
+        version (int): Asset version.
+
+    Returns:
+        bool: True if directory was created, False if it already existed.
+    """
     asset_dir = _asset_dir(humalab_config, name, version)
     if not os.path.exists(asset_dir):
         os.makedirs(asset_dir, exist_ok=True)
         return True
     return False
 
-def download(name: str, 
+def download(name: str,
              version: int | None=None,
              project: str = DEFAULT_PROJECT,
-             
+
              host: str | None = None,
              api_key: str | None = None,
              timeout: float | None = None,
              ) -> Any:
+    """Download a resource from HumaLab.
+
+    Args:
+        name (str): The resource name to download.
+        version (int | None): Optional specific version. If None, downloads latest.
+        project (str): The project name. Defaults to DEFAULT_PROJECT.
+        host (str | None): Optional API host override.
+        api_key (str | None): Optional API key override.
+        timeout (float | None): Optional timeout override.
+
+    Returns:
+        ResourceFile | URDFFile: The downloaded resource file object.
+    """
     humalab_config = HumalabConfig()
 
     api_client = HumaLabApiClient(base_url=host,
@@ -61,10 +94,25 @@ def list_resources(project: str = DEFAULT_PROJECT,
                    limit: int = 20,
                    offset: int = 0,
                    latest_only: bool = True,
-                    
+
                     host: str | None = None,
                     api_key: str | None = None,
                     timeout: float | None = None,) -> list[ResourceFile]:
+    """List available resources from HumaLab.
+
+    Args:
+        project (str): The project name. Defaults to DEFAULT_PROJECT.
+        resource_types (Optional[list[str | ResourceType]]): Filter by resource types.
+        limit (int): Maximum number of resources to return. Defaults to 20.
+        offset (int): Pagination offset. Defaults to 0.
+        latest_only (bool): Only return latest versions. Defaults to True.
+        host (str | None): Optional API host override.
+        api_key (str | None): Optional API key override.
+        timeout (float | None): Optional timeout override.
+
+    Returns:
+        list[ResourceFile]: List of resource file objects.
+    """
     api_client = HumaLabApiClient(base_url=host,
                                   api_key=api_key,
                                   timeout=timeout)

humalab/constants.py

@@ -1,11 +1,16 @@
+"""Constants and enumerations used throughout the HumaLab SDK."""
+
 from enum import Enum
 
 
 RESERVED_NAMES = {
-    "sceanario"
+    "sceanario",
+    "seed",
 }
+"""Set of reserved names that cannot be used for metric or artifact keys."""
 
 DEFAULT_PROJECT = "default"
+"""Default project name used when no project is specified."""
 
 
 class ArtifactType(Enum):
@@ -17,6 +22,10 @@ class ArtifactType(Enum):
 
 
 class MetricType(Enum):
+    """Enumeration of metric types.
+
+    Maps to corresponding artifact types for metrics and scenario statistics.
+    """
     METRICS = ArtifactType.METRICS.value
     SCENARIO_STATS = ArtifactType.SCENARIO_STATS.value
 

humalab/dists/__init__.py

@@ -1,3 +1,10 @@
+"""Probability distributions for scenario randomization.
+
+This module provides various probability distribution classes used in scenario generation,
+including uniform, gaussian, bernoulli, categorical, discrete, log-uniform, and truncated
+gaussian distributions. Each supports 0D (scalar) and multi-dimensional (1D-3D) variants.
+"""
+
 from .bernoulli import Bernoulli
 from .categorical import Categorical
 from .discrete import Discrete

humalab/dists/bernoulli.py

@@ -4,6 +4,11 @@ from typing import Any
 import numpy as np
 
 class Bernoulli(Distribution):
+    """Bernoulli distribution for binary outcomes.
+
+    Samples binary values (0 or 1) with a specified probability of success.
+    Supports scalar outputs as well as multi-dimensional arrays with 1D variants.
+    """
     def __init__(self,
                  generator: np.random.Generator,
                  p: float | Any,
@@ -22,6 +27,15 @@ class Bernoulli(Distribution):
 
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (p).
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """
         arg1 = args[0]
         if dimensions == 0:
             if not isinstance(arg1, (int, float)):
@@ -37,9 +51,19 @@ class Bernoulli(Distribution):
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the Bernoulli distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled binary value(s) (0 or 1).
+        """
         return self._generator.binomial(n=1, p=self._p, size=self._size)
 
     def __repr__(self) -> str:
+        """String representation of the Bernoulli distribution.
+
+        Returns:
+            str: String representation showing p and size.
+        """
         return f"Bernoulli(p={self._p}, size={self._size})"
     
     @staticmethod

humalab/dists/categorical.py

@@ -3,6 +3,12 @@ from humalab.dists.distribution import Distribution
 import numpy as np
 
 class Categorical(Distribution):
+    """Categorical distribution for discrete choices.
+
+    Samples from a list of choices with optional weights. If weights are not
+    provided, samples uniformly from all choices. Weights are automatically
+    normalized to sum to 1.
+    """
     def __init__(self,
                  generator: np.random.Generator,
                  choices: list, 
@@ -27,12 +33,31 @@ class Categorical(Distribution):
 
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (choices, weights).
+
+        Returns:
+            bool: Always returns True as categorical accepts any parameters.
+        """
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the categorical distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled choice(s) from the list.
+        """
         return self._generator.choice(self._choices, size=self._size, p=self._weights)
 
     def __repr__(self) -> str:
+        """String representation of the categorical distribution.
+
+        Returns:
+            str: String representation showing choices, size, and weights.
+        """
         return f"Categorical(choices={self._choices}, size={self._size}, weights={self._weights})"
     
     @staticmethod

humalab/dists/discrete.py

@@ -4,6 +4,12 @@ from typing import Any
 import numpy as np
 
 class Discrete(Distribution):
+    """Discrete uniform distribution over integers.
+
+    Samples integer values uniformly from a range [low, high). The endpoint
+    parameter controls whether the upper bound is inclusive or exclusive.
+    Supports scalar outputs as well as multi-dimensional arrays with 1D variants.
+    """
     def __init__(self, 
                  generator: np.random.Generator,
                  low: int | Any, 
@@ -29,6 +35,15 @@ class Discrete(Distribution):
     
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (low, high).
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """
         arg1 = args[0]
         arg2 = args[1]
         if dimensions == 0:
@@ -50,9 +65,19 @@ class Discrete(Distribution):
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the discrete distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled integer value(s) from [low, high).
+        """
         return self._generator.integers(self._low, self._high, size=self._size, endpoint=self._endpoint)
 
     def __repr__(self) -> str:
+        """String representation of the discrete distribution.
+
+        Returns:
+            str: String representation showing low, high, size, and endpoint.
+        """
         return f"Discrete(low={self._low}, high={self._high}, size={self._size}, endpoint={self._endpoint})"
     
     @staticmethod

humalab/dists/distribution.py

@@ -3,6 +3,12 @@ from abc import ABC, abstractmethod
 import numpy as np
 
 class Distribution(ABC):
+    """Abstract base class for probability distributions.
+
+    All distribution classes inherit from this base class and must implement
+    the _sample() method. Distributions maintain a random number generator
+    and track the last sampled value.
+    """
     def __init__(self,
                  generator: np.random.Generator) -> None:
         """
@@ -27,6 +33,11 @@ class Distribution(ABC):
 
     @abstractmethod
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the distribution.
+
+        Returns:
+            int | float | np.ndarray: The sampled value(s).
+        """
         pass
 
     @property

humalab/dists/gaussian.py

@@ -4,6 +4,12 @@ import numpy as np
 
 
 class Gaussian(Distribution):
+    """Gaussian (normal) distribution.
+
+    Samples values from a normal distribution with specified mean (loc) and
+    standard deviation (scale). Supports scalar outputs as well as multi-dimensional
+    arrays with 1D, 2D, or 3D variants.
+    """
     def __init__(self,
                  generator: np.random.Generator,
                  loc: float | Any,
@@ -25,6 +31,15 @@ class Gaussian(Distribution):
 
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (loc, scale).
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """
         arg1 = args[0]
         arg2 = args[1]
         if dimensions == 0:
@@ -46,9 +61,19 @@ class Gaussian(Distribution):
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the Gaussian distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled value(s) from N(loc, scale).
+        """
         return self._generator.normal(loc=self._loc, scale=self._scale, size=self._size)
 
     def __repr__(self) -> str:
+        """String representation of the Gaussian distribution.
+
+        Returns:
+            str: String representation showing loc, scale, and size.
+        """
         return f"Gaussian(loc={self._loc}, scale={self._scale}, size={self._size})"
     
     @staticmethod

humalab/dists/log_uniform.py

@@ -4,6 +4,13 @@ from typing import Any
 import numpy as np
 
 class LogUniform(Distribution):
+    """Log-uniform distribution.
+
+    Samples values uniformly in log-space, useful for hyperparameters that
+    span multiple orders of magnitude (e.g., learning rates). The result is
+    exp(uniform(log(low), log(high))). Supports scalar outputs as well as
+    multi-dimensional arrays with 1D variants.
+    """
     def __init__(self, 
                  generator: np.random.Generator,
                  low: float | Any,
@@ -25,6 +32,15 @@ class LogUniform(Distribution):
     
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (low, high).
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """
         arg1 = args[0]
         arg2 = args[1]
         if dimensions == 0:
@@ -46,9 +62,19 @@ class LogUniform(Distribution):
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the log-uniform distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled value(s) in log-space.
+        """
         return np.exp(self._generator.uniform(self._log_low, self._log_high, size=self._size))
-    
+
     def __repr__(self) -> str:
+        """String representation of the log-uniform distribution.
+
+        Returns:
+            str: String representation showing low, high, and size.
+        """
         return f"LogUniform(low={np.exp(self._log_low)}, high={np.exp(self._log_high)}, size={self._size})"
 
     @staticmethod

humalab/dists/truncated_gaussian.py

@@ -4,6 +4,13 @@ import numpy as np
 
 
 class TruncatedGaussian(Distribution):
+    """Truncated Gaussian (normal) distribution.
+
+    Samples values from a normal distribution with specified mean (loc) and
+    standard deviation (scale), but constrained to lie within [low, high].
+    Values outside the bounds are resampled until they fall within range.
+    Supports scalar outputs as well as multi-dimensional arrays with 1D, 2D, or 3D variants.
+    """
     def __init__(self,
                  generator: np.random.Generator,
                  loc: float | Any,
@@ -31,6 +38,15 @@ class TruncatedGaussian(Distribution):
 
     @staticmethod
     def validate(dimensions: int, *args) -> bool:
+        """Validate distribution parameters for the given dimensions.
+
+        Args:
+            dimensions (int): The number of dimensions (0 for scalar, -1 for any).
+            *args: The distribution parameters (loc, scale, low, high).
+
+        Returns:
+            bool: True if parameters are valid, False otherwise.
+        """
         arg1 = args[0]
         arg2 = args[1]
         arg3 = args[2]
@@ -66,6 +82,14 @@ class TruncatedGaussian(Distribution):
         return True
     
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the truncated Gaussian distribution.
+
+        Samples are generated from N(loc, scale) and resampled if they fall
+        outside [low, high].
+
+        Returns:
+            int | float | np.ndarray: Sampled value(s) within [low, high].
+        """
         samples = self._generator.normal(loc=self._loc, scale=self._scale, size=self._size)
         mask = (samples < self._low) | (samples > self._high)
         while np.any(mask):
@@ -74,6 +98,11 @@ class TruncatedGaussian(Distribution):
         return samples
 
     def __repr__(self) -> str:
+        """String representation of the truncated Gaussian distribution.
+
+        Returns:
+            str: String representation showing loc, scale, low, high, and size.
+        """
         return f"TruncatedGaussian(loc={self._loc}, scale={self._scale}, low={self._low}, high={self._high}, size={self._size})"
     
     @staticmethod