humalab 0.1.0__py3-none-any.whl

humalab/__init__.py

@@ -0,0 +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

@@ -0,0 +1,10 @@
+"""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__ = ["download", "list_resources", "ResourceFile", "URDFFile"]

humalab/assets/archive.py

@@ -0,0 +1,101 @@
+import shutil
+import zipfile
+import tarfile
+import gzip
+import bz2
+import lzma
+from pathlib import Path
+
+
+try:
+    import py7zr        # for .7z
+except ImportError:
+    py7zr = None
+
+try:
+    import rarfile      # for .rar
+except ImportError:
+    rarfile = None
+
+
+# ---------- Detection ---------------------------------------------------------
+def detect_archive_type(path: str | Path) -> str:
+    """Return a simple string label for the archive type, else 'unknown'."""
+    p = Path(path).with_suffix("").name.lower()  # strip double-suffix like .tar.gz
+    ext = Path(path).suffix.lower()
+
+    if ext == ".zip":
+        return "zip"
+    if ext in {".tar"}:
+        return "tar"
+    if ext in {".gz"} and p.endswith(".tar"):
+        return "tar.gz"
+    if ext in {".bz2"} and p.endswith(".tar"):
+        return "tar.bz2"
+    if ext in {".xz"} and p.endswith(".tar"):
+        return "tar.xz"
+    if ext == ".gz":
+        return "gzip"
+    if ext == ".bz2":
+        return "bzip2"
+    if ext == ".xz":
+        return "xz"
+    if ext == ".7z":
+        return "7z"
+    if ext == ".rar":
+        return "rar"
+    return "unknown"
+
+
+def _extract_stream(open_func, path: Path, out_dir: Path):
+    """Helper for single-file compressed streams (.gz, .bz2, .xz)."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_file = out_dir / path.with_suffix("").name
+    with open_func(path, "rb") as f_in, open(out_file, "wb") as f_out:
+        shutil.copyfileobj(f_in, f_out)
+
+
+# ---------- Extraction --------------------------------------------------------
+def extract_archive(path: str | Path, out_dir: str | Path) -> None:
+    """Detect the archive type and extract it into out_dir."""
+    path, out_dir = Path(path), Path(out_dir)
+    archive_type = detect_archive_type(path)
+
+    match archive_type:
+        # --- ZIP
+        case "zip":
+            with zipfile.ZipFile(path) as zf:
+                zf.extractall(out_dir)
+
+        # --- tar.* (auto-deduces compression)
+        case "tar" | "tar.gz" | "tar.bz2" | "tar.xz":
+            with tarfile.open(path, mode="r:*") as tf:
+                tf.extractall(out_dir)
+
+        # --- single-file streams
+        case "gzip":
+            _extract_stream(gzip.open, path, out_dir)
+        case "bzip2":
+            _extract_stream(bz2.open, path, out_dir)
+        case "xz":
+            _extract_stream(lzma.open, path, out_dir)
+
+        # --- 7-Zip
+        case "7z":
+            if py7zr is None:
+                raise ImportError("py7zr not installed - run `pip install py7zr`")
+            with py7zr.SevenZipFile(path, mode="r") as z:
+                z.extractall(path=out_dir)
+
+        # --- RAR
+        case "rar":
+            if rarfile is None:
+                raise ImportError("rarfile not installed - run `pip install rarfile`")
+            if not rarfile.is_rarfile(path):
+                raise rarfile.BadRarFile(f"{path} is not a valid RAR archive")
+            with rarfile.RarFile(path) as rf:
+                rf.extractall(out_dir)
+
+        # --- fallback
+        case _:
+            raise ValueError(f"Unsupported or unknown archive type: {archive_type}")

humalab/assets/files/__init__.py

@@ -0,0 +1,4 @@
+from .resource_file import ResourceFile
+from .urdf_file import URDFFile
+
+__all__ = ["ResourceFile", "URDFFile"]

humalab/assets/files/resource_file.py

@@ -0,0 +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 | 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 = 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) -> 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

@@ -0,0 +1,103 @@
+import os
+import glob
+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__(project=project,
+                         name=name, 
+                         version=version,
+                         description=description,
+                         filename=filename,
+                         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):
+        """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)
+                try:
+                    os.remove(self.filename)
+                except Exception as 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, "**")
+            search_pattern = os.path.join(search_path, resource_filename)
+            files = glob.glob(search_pattern, recursive=True)
+            if len(files) > 0:
+                found_filename = files[0]
+        
+        if found_filename is None:
+            ext = "urdf"
+            search_pattern = os.path.join(working_path, "**", f"*.{ext}")
+            files = glob.glob(search_pattern, recursive=True)
+            if len(files) > 0:
+                found_filename = files[0]
+        return found_filename
+
+    @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

@@ -0,0 +1,50 @@
+"""Constants and enumerations used throughout the HumaLab SDK."""
+
+from enum import Enum
+
+
+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

@@ -0,0 +1,24 @@
+"""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
+from .gaussian import Gaussian
+from .log_uniform import LogUniform
+from .truncated_gaussian import TruncatedGaussian
+from .uniform import Uniform
+
+__all__ = [
+    "Bernoulli",
+    "Categorical",
+    "Discrete",
+    "LogUniform",
+    "Gaussian",
+    "TruncatedGaussian",
+    "Uniform",
+]

humalab/dists/bernoulli.py

@@ -0,0 +1,84 @@
+from humalab.dists.distribution import Distribution
+
+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,
+                 size: int | tuple[int, ...] | None = None) -> None:
+        """
+        Initialize the Bernoulli distribution.
+
+        Args:
+            generator (np.random.Generator): The random number generator.
+            p (float | Any): The probability of success.
+            size (int | tuple[int, ...] | None): The size of the output.
+        """
+        super().__init__(generator=generator)
+        self._p = p
+        self._size = size
+
+    @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)):
+                return False
+            return True
+        if dimensions == -1:
+            return True
+        if not isinstance(arg1, (int, float)):
+            if isinstance(arg1, (list, np.ndarray)):
+                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
+    def create(generator: np.random.Generator, 
+               p: float | Any, 
+               size: int | tuple[int, ...] | None = None) -> 'Bernoulli':
+        """
+        Create a Bernoulli distribution.
+
+        Args:
+            generator (np.random.Generator): The random number generator.
+            p (float | Any): The probability of success.
+            size (int | tuple[int, ...] | None): The size of the output.
+
+        Returns:
+            Bernoulli: The created Bernoulli distribution.
+        """
+        return Bernoulli(generator=generator, p=p, size=size)