humalab 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

humalab/__init__.py

@@ -1,9 +1,34 @@
+"""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
+from humalab import scenarios
 from humalab.run import Run
+from humalab.constants import MetricDimType, GraphType
+# from humalab import evaluators
 
 __all__ = [
     "init",
     "finish",
     "login",
+    "assets",
+    "metrics",
+    "scenarios",
     "Run",
+    "MetricDimType",
+    "GraphType",
+#    "evaluators",
 ]

humalab/assets/__init__.py

@@ -1,4 +1,10 @@
-from .resource_manager import ResourceManager
+"""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
 
-__all__ = ["ResourceManager", "ResourceFile", "URDFFile"]
+__all__ = ["download", "list_resources", "ResourceFile", "URDFFile"]

humalab/assets/files/resource_file.py

@@ -1,41 +1,131 @@
 from datetime import datetime
+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"
+    MESH = "mesh"
+    VIDEO = "video"
+    IMAGE = "image"
+    DATA = "data"
+
 
 
 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, 
                  filename: str,
-                 resource_type: str,
+                 resource_type: str | ResourceType,
+                 project: str = DEFAULT_PROJECT,
                  description: str | None = None,
                  created_at: datetime | None = None):
+        self._project = project
         self._name = name
         self._version = version
         self._filename = filename
-        self._resource_type = resource_type
+        self._resource_type = ResourceType(resource_type)
         self._description = description
         self._created_at = created_at
 
+    @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) -> str:
+    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

@@ -1,45 +1,73 @@
-from datetime import datetime
 import os
 import glob
-from humalab.assets.files.resource_file import ResourceFile
+from datetime import datetime
+
+from humalab.assets.files.resource_file import ResourceFile, ResourceType
 from humalab.assets.archive import extract_archive
+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,
                  filename: str,
+                 project: str = DEFAULT_PROJECT,
                  urdf_filename: str | None = None,
                  description: str | None = None,
                  created_at: datetime | None = None,):
-        super().__init__(name=name, 
+        super().__init__(project=project,
+                         name=name, 
                          version=version,
                          description=description,
                          filename=filename,
-                         resource_type="URDF", 
+                         resource_type=ResourceType.URDF, 
                          created_at=created_at)
         self._urdf_base_filename = urdf_filename
         self._urdf_filename, self._root_path = self._extract()
         self._urdf_filename = os.path.join(self._urdf_filename, self._urdf_filename)
         
     def _extract(self):
-        working_path = os.path.dirname(self._filename)
-        if os.path.exists(self._filename):
-            _, ext = os.path.splitext(self._filename)
+        """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)
             ext = ext.lstrip('.')  # Remove leading dot
             if ext.lower() != "urdf":
-                extract_archive(self._filename, working_path)
+                extract_archive(self.filename, working_path)
                 try:
-                    os.remove(self._filename)
+                    os.remove(self.filename)
                 except Exception as e:
-                    print(f"Error removing saved file {self._filename}: {e}")
+                    print(f"Error removing saved file {self.filename}: {e}")
         local_filename = self.search_resource_file(self._urdf_base_filename, working_path)
         if local_filename is None:
             raise ValueError(f"Resource filename {self._urdf_base_filename} not found in {working_path}")
         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, "**")
@@ -58,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

@@ -0,0 +1,139 @@
+from humalab.constants import DEFAULT_PROJECT
+from humalab.assets.files.resource_file import ResourceFile, ResourceType
+from humalab.humalab_config import HumalabConfig
+from humalab.humalab_api_client import HumaLabApiClient
+from humalab.assets.files.urdf_file import URDFFile
+import os
+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,
+             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,
+                                  api_key=api_key,
+                                  timeout=timeout)
+
+    resource = api_client.get_resource(project_name=project, name=name, version=version)
+    filename = os.path.basename(resource['resource_url'])
+    filename = os.path.join(_asset_dir(humalab_config, name, resource["version"]), filename)
+    if _create_asset_dir(humalab_config, name, resource["version"]):
+        file_content = api_client.download_resource(project_name=project, name="lerobot")
+        with open(filename, "wb") as f:
+            f.write(file_content)
+    
+    if resource["resource_type"].lower() == "urdf":
+        return URDFFile(project=project,
+                        name=name,
+                        version=resource["version"],
+                        description=resource.get("description"),
+                        filename=filename,
+                        urdf_filename=resource.get("filename"),
+                        created_at=resource.get("created_at"))
+
+    return ResourceFile(project=project,
+                        name=name, 
+                        version=resource["version"], 
+                        filename=filename,
+                        resource_type=resource["resource_type"],
+                        description=resource.get("description"),
+                        created_at=resource.get("created_at"))
+
+def list_resources(project: str = DEFAULT_PROJECT,
+                   resource_types: Optional[list[str | ResourceType]] = None,
+                   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)
+
+    resource_type_string = None
+    if resource_types:
+        resource_type_strings = {rt.value if isinstance(rt, ResourceType) else rt for rt in resource_types}
+        resource_type_string = ",".join(resource_type_strings)
+    resp = api_client.get_resources(project_name=project,
+                                    resource_types=resource_type_string,
+                                    limit=limit,
+                                    offset=offset,
+                                    latest_only=latest_only)
+    resources = resp.get("resources", [])
+    ret_list = []
+    for resource in resources:
+        ret_list.append(ResourceFile(name=resource["name"],
+                                    version=resource.get("version"),
+                                    project=project,
+                                    filename=resource.get("filename"),
+                                    resource_type=resource.get("resource_type"),
+                                    description=resource.get("description"),
+                                    created_at=resource.get("created_at")))
+    return ret_list

humalab/constants.py

@@ -1,7 +1,50 @@
+"""Constants and enumerations used throughout the HumaLab SDK."""
+
 from enum import Enum
 
-class EpisodeStatus(Enum):
-    PASS = "pass"
-    FAILED = "failed"
-    CANCELED = "canceled"
-    ERROR = "error"
+
+RESERVED_NAMES = {
+    "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):
+    """Types of artifacts that can be stored"""
+    METRICS = "metrics" # Run & Episode
+    SCENARIO_STATS = "scenario_stats" # Run only
+    PYTHON = "python" # Run & Episode
+    CODE = "code" # Run & Episode (YAML)
+
+
+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
+
+
+class GraphType(Enum):
+    """Types of graphs supported by Humalab."""
+    NUMERIC = "numeric"
+    LINE = "line"
+    BAR = "bar"
+    SCATTER = "scatter"
+    HISTOGRAM = "histogram"
+    GAUSSIAN = "gaussian"
+    HEATMAP = "heatmap"
+    THREE_D_MAP = "3d_map"
+
+
+class MetricDimType(Enum):
+    """Types of metric dimensions"""
+    ZERO_D = "0d"
+    ONE_D = "1d"
+    TWO_D = "2d"
+    THREE_D = "3d"

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)):
@@ -31,14 +45,25 @@ class Bernoulli(Distribution):
             return True
         if not isinstance(arg1, (int, float)):
             if isinstance(arg1, (list, np.ndarray)):
-                if len(arg1) > dimensions:
+                if len(arg1) != dimensions:
                     return False
+
         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:
@@ -41,18 +56,28 @@ class Discrete(Distribution):
             return True
         if not isinstance(arg1, int):
             if isinstance(arg1, (list, np.ndarray)):
-                if len(arg1) > dimensions:
+                if len(arg1) != dimensions:
                     return False
         if not isinstance(arg2, int):
             if isinstance(arg2, (list, np.ndarray)):
-                if len(arg2) > dimensions:
+                if len(arg2) != dimensions:
                     return False
         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