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

humalab/dists/uniform.py

@@ -4,6 +4,11 @@ from typing import Any
 import numpy as np
 
 class Uniform(Distribution):
+    """Uniform distribution over a continuous or discrete range.
+
+    Samples values uniformly from the half-open interval [low, high). Supports
+    scalar outputs as well as multi-dimensional arrays with 1D, 2D, or 3D variants.
+    """
     def __init__(self, 
                  generator: np.random.Generator,
                  low: float | Any, 
@@ -25,6 +30,15 @@ class Uniform(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 +60,19 @@ class Uniform(Distribution):
         return True
 
     def _sample(self) -> int | float | np.ndarray:
+        """Generate a sample from the uniform distribution.
+
+        Returns:
+            int | float | np.ndarray: Sampled value(s) from [low, high).
+        """
         return self._generator.uniform(self._low, self._high, size=self._size)
 
     def __repr__(self) -> str:
+        """String representation of the uniform distribution.
+
+        Returns:
+            str: String representation showing low, high, and size.
+        """
         return f"Uniform(low={self._low}, high={self._high}, size={self._size})"
     
     @staticmethod

humalab/episode.py

@@ -12,6 +12,31 @@ from humalab.utils import is_standard_type
 
 
 class Episode:
+    """Represents a single episode within a run.
+
+    An Episode is a context manager that tracks a single execution instance of a
+    scenario. It provides access to scenario configuration values, supports metric
+    logging, and manages episode lifecycle with various completion statuses.
+
+    Episodes can be finished with different statuses:
+    - SUCCESS: Episode completed successfully
+    - FAILED: Episode failed
+    - CANCELED: Episode was discarded/canceled
+    - ERRORED: Episode encountered an error
+
+    Use as a context manager to automatically handle episode lifecycle:
+        with episode:
+            # Your code here
+            pass
+
+    Attributes:
+        run_id (str): The unique identifier of the parent run.
+        episode_id (str): The unique identifier for this episode.
+        scenario (DictConfig | ListConfig): The resolved scenario configuration.
+        status (EpisodeStatus): The current status of the episode.
+        episode_vals (dict): The sampled values from scenario distributions.
+        is_finished (bool): Whether the episode has been finalized.
+    """
     def __init__(self, 
                  run_id: str, 
                  episode_id: str, 
@@ -35,32 +60,64 @@ class Episode:
 
     @property
     def run_id(self) -> str:
+        """The unique identifier of the parent run.
+
+        Returns:
+            str: The run ID.
+        """
         return self._run_id
-    
+
     @property
     def episode_id(self) -> str:
+        """The unique identifier for this episode.
+
+        Returns:
+            str: The episode ID.
+        """
         return self._episode_id
 
     @property
     def scenario(self) -> DictConfig | ListConfig:
+        """The resolved scenario configuration for this episode.
+
+        Returns:
+            DictConfig | ListConfig: The scenario configuration.
+        """
         return self._scenario_conf
-    
+
     @property
     def status(self) -> EpisodeStatus:
+        """The current status of the episode.
+
+        Returns:
+            EpisodeStatus: The episode status.
+        """
         return self._episode_status
-    
+
     @property
     def episode_vals(self) -> dict:
+        """The sampled values from scenario distributions.
+
+        Returns:
+            dict: Dictionary mapping scenario variable names to their sampled values.
+        """
         return self._episode_vals
-    
+
     @property
     def is_finished(self) -> bool:
+        """Whether the episode has been finalized.
+
+        Returns:
+            bool: True if the episode is finished, False otherwise.
+        """
         return self._is_finished
     
     def __enter__(self):
+        """Enter the episode context."""
         return self
 
     def __exit__(self, exception_type, exception_value, exception_traceback):
+        """Exit the episode context and finalize the episode."""
         if self._is_finished:
             return
         if exception_type is not None:
@@ -70,16 +127,51 @@ class Episode:
             self.finish(status=EpisodeStatus.SUCCESS)
 
     def __getattr__(self, name: Any) -> Any:
+        """Access scenario configuration values as attributes.
+
+        Allows accessing scenario configuration using dot notation (e.g., episode.my_param).
+
+        Args:
+            name (Any): The attribute/key name from scenario configuration.
+
+        Returns:
+            Any: The value from scenario configuration.
+
+        Raises:
+            AttributeError: If the attribute is not in scenario configuration.
+        """
         if name in self._scenario_conf:
             return self._scenario_conf[name]
         raise AttributeError(f"'Scenario' object has no attribute '{name}'")
 
     def __getitem__(self, key: Any) -> Any:
+        """Access scenario configuration values using subscript notation.
+
+        Allows accessing scenario configuration using bracket notation (e.g., episode['my_param']).
+
+        Args:
+            key (Any): The key name from scenario configuration.
+
+        Returns:
+            Any: The value from scenario configuration.
+
+        Raises:
+            KeyError: If the key is not in scenario configuration.
+        """
         if key in self._scenario_conf:
             return self._scenario_conf[key]
         raise KeyError(f"'Scenario' object has no key '{key}'")
 
     def add_metric(self, name: str, metric: Metrics) -> None:
+        """Add a metric to track for this episode.
+
+        Args:
+            name (str): The name of the metric.
+            metric (Metrics): The metric instance to add.
+
+        Raises:
+            ValueError: If the name is already used.
+        """
         if name in self._logs:
             raise ValueError(f"{name} is a reserved name and is not allowed.")
         self._logs[name] = metric
@@ -101,6 +193,16 @@ class Episode:
         )
 
     def log(self, data: dict, x: dict | None = None, replace: bool = False) -> None:
+        """Log data points or values for the episode.
+
+        Args:
+            data (dict): Dictionary of key-value pairs to log.
+            x (dict | None): Optional dictionary of x-axis values for each key.
+            replace (bool): Whether to replace existing values. Defaults to False.
+
+        Raises:
+            ValueError: If a key is reserved or logging fails.
+        """
         for key, value in data.items():
             if key in RESERVED_NAMES:
                 raise ValueError(f"{key} is a reserved name and is not allowed.")
@@ -127,15 +229,24 @@ class Episode:
         return OmegaConf.to_yaml(self._scenario_conf)
     
     def discard(self) -> None:
+        """Mark the episode as discarded/canceled."""
         self._finish(EpisodeStatus.CANCELED)
 
     def success(self) -> None:
+        """Mark the episode as successfully completed."""
         self._finish(EpisodeStatus.SUCCESS)
-    
+
     def fail(self) -> None:
+        """Mark the episode as failed."""
         self._finish(EpisodeStatus.FAILED)
 
     def finish(self, status: EpisodeStatus, err_msg: str | None = None) -> None:
+        """Finish the episode with a specific status.
+
+        Args:
+            status (EpisodeStatus): The final status of the episode.
+            err_msg (str | None): Optional error message if the episode errored.
+        """
         if self._is_finished:
             return
         self._is_finished = True
@@ -155,7 +266,7 @@ class Episode:
                 pickled = pickle.dumps(metric_val["value"])
                 self._api_client.upload_python(
                     artifact_key=key,
-                    run_id=self._id,
+                    run_id=self._run_id,
                     episode_id=self._episode_id,
                     pickled_bytes=pickled
                 )
@@ -164,11 +275,10 @@ class Episode:
                 pickled = pickle.dumps(metric_val)
                 self._api_client.upload_metrics(
                     artifact_key=key,
-                    run_id=self._id,
+                    run_id=self._run_id,
                     episode_id=self._episode_id,
                     pickled_bytes=pickled,
                     graph_type=value.graph_type.value,
-                    metric_dim_type=value.metric_dim_type.value
                 )
             elif isinstance(value, Code):
                 self._api_client.upload_code(

humalab/humalab.py

@@ -20,8 +20,20 @@ _cur_run: Run | None = None
 
 def _pull_scenario(client: HumaLabApiClient,
                    project: str,
-                   scenario: str | list | dict | None = None,
-                   scenario_id: str | None = None,) -> str | list | dict | None:
+                   seed: int | None = None,
+                   scenario: str | list | dict | Scenario | None = None,
+                   scenario_id: str | None = None,) -> Scenario:
+    """Pull a scenario from the server if scenario_id is provided.
+
+    Args:
+        client (HumaLabApiClient): API client instance.
+        project (str): Project name.
+        scenario (str | list | dict | None): Local scenario configuration.
+        scenario_id (str | None): ID of scenario to pull from server.
+
+    Returns:
+        str | list | dict | None: The scenario configuration.
+    """
     if scenario_id is not None:
         scenario_arr = scenario_id.split(":")
         if len(scenario_arr) < 1:
@@ -31,9 +43,22 @@ def _pull_scenario(client: HumaLabApiClient,
 
         scenario_response = client.get_scenario(
             project_name=project,
-            uuid=scenario_real_id, version=scenario_version)
-        return scenario_response["yaml_content"]
-    return scenario
+            uuid=scenario_real_id, 
+            version=scenario_version)
+        final_scenario = scenario_response["yaml_content"]
+    else:
+        final_scenario = scenario
+
+    if isinstance(final_scenario, Scenario):
+        scenario_inst = final_scenario
+    else:
+        scenario_inst = Scenario()
+        scenario_inst.init(scenario=final_scenario, 
+                           seed=seed, 
+                           scenario_id=scenario_id,
+                           #num_env=num_env,
+                           )
+    return scenario_inst
 
 @contextmanager
 def init(project: str | None = None,
@@ -41,7 +66,7 @@ def init(project: str | None = None,
          description: str | None = None,
          id: str | None = None,
          tags: list[str] | None = None,
-         scenario: str | list | dict | None = None,
+         scenario: str | list | dict | Scenario | None = None,
          scenario_id: str | None = None,
          seed: int | None=None,
          auto_create_scenario: bool = False,
@@ -80,19 +105,14 @@ def init(project: str | None = None,
         api_client = HumaLabApiClient(base_url=base_url,
                                       api_key=api_key,
                                       timeout=timeout)
-        final_scenario = _pull_scenario(client=api_client, 
+        scenario_inst = _pull_scenario(client=api_client, 
                                         project=project,
+                                        seed=seed,
                                         scenario=scenario, 
                                         scenario_id=scenario_id)
         
         project_resp = api_client.create_project(name=project)
-
-        scenario_inst = Scenario()
-        scenario_inst.init(scenario=final_scenario, 
-                           seed=seed, 
-                           scenario_id=scenario_id,
-                           #num_env=num_env,
-                           )
+        
         if scenario_id is None and scenario is not None and auto_create_scenario:
             scenario_response = api_client.create_scenario(
                 project_name=project_resp['name'],
@@ -159,10 +179,17 @@ def init(project: str | None = None,
             finish(status=RunStatus.FINISHED)
 
 def discard() -> None:
+    """Discard the current run by finishing it with CANCELED status."""
     finish(status=RunStatus.CANCELED)
 
 def finish(status: RunStatus = RunStatus.FINISHED,
            err_msg: str | None = None) -> None:
+    """Finish the current run.
+
+    Args:
+        status (RunStatus): The final status of the run. Defaults to FINISHED.
+        err_msg (str | None): Optional error message if the run errored.
+    """
     global _cur_run
     if _cur_run:
         _cur_run.finish(status=status, err_msg=err_msg)
@@ -173,6 +200,18 @@ def login(api_key: str | None = None,
           host: str | None = None,
           force: bool | None = None,
           timeout: float | None = None) -> bool:
+    """Configure HumaLab authentication and connection settings.
+
+    Args:
+        api_key (str | None): API key for authentication.
+        relogin (bool | None): Unused parameter (for compatibility).
+        host (str | None): API host URL.
+        force (bool | None): Unused parameter (for compatibility).
+        timeout (float | None): Request timeout in seconds.
+
+    Returns:
+        bool: Always returns True.
+    """
     humalab_config = HumalabConfig()
     humalab_config.api_key = api_key or humalab_config.api_key
     humalab_config.base_url = host or humalab_config.base_url

humalab/humalab_api_client.py

@@ -38,13 +38,13 @@ class HumaLabApiClient:
         Initialize the HumaLab API client.
         
         Args:
-            base_url: Base URL for the HumaLab service (defaults to localhost:8000)
+            base_url: Base URL for the HumaLab service (defaults to https://api.humalab.ai)
             api_key: API key for authentication (defaults to HUMALAB_API_KEY env var)
             timeout: Request timeout in seconds
         """
         humalab_config = HumalabConfig()
-        self.base_url = base_url or os.getenv("HUMALAB_SERVICE_URL", "http://localhost:8000") or humalab_config.base_url
-        self.api_key = api_key or os.getenv("HUMALAB_API_KEY") or humalab_config.api_key
+        self.base_url = base_url or humalab_config.base_url or os.getenv("HUMALAB_SERVICE_URL", "https://api.humalab.ai")
+        self.api_key = api_key or humalab_config.api_key or os.getenv("HUMALAB_API_KEY")
         self.timeout = timeout or humalab_config.timeout or 30.0  # Default timeout of 30 seconds
         
         # Ensure base_url ends without trailing slash
@@ -885,7 +885,6 @@ class HumaLabApiClient:
         run_id: str,
         pickled_bytes: bytes,
         graph_type: str,
-        metric_dim_type: str
     ) -> Dict[str, Any]:
         """
         Upload scenario stats artifact (pickled Python dict data).
@@ -905,7 +904,6 @@ class HumaLabApiClient:
         data = {
             'artifact_key': artifact_key,
             'run_id': run_id,
-            'metric_dim_type': metric_dim_type,
             'graph_type': graph_type
         }
 
@@ -940,7 +938,6 @@ class HumaLabApiClient:
         artifact_key: str,
         pickled_bytes: bytes,
         graph_type: str,
-        metric_dim_type: str,
         episode_id: str | None = None,
     ) -> Dict[str, Any]:
         """
@@ -951,7 +948,6 @@ class HumaLabApiClient:
             artifact_key: Artifact key
             pickled_bytes: Pickled metrics data as bytes
             graph_type: Optional new graph type
-            metric_dim_type: Optional new metric dimension type
             episode_id: Optional new episode ID
 
         Returns:
@@ -960,7 +956,6 @@ class HumaLabApiClient:
         data = {
             "run_id": run_id,
             "artifact_key": artifact_key,
-            'metric_dim_type': metric_dim_type,
             'graph_type': graph_type
         }
         files = {'file': pickled_bytes}

humalab/humalab_config.py

@@ -3,6 +3,18 @@ import yaml
 import os
 
 class HumalabConfig:
+    """Manages HumaLab SDK configuration settings.
+
+    Configuration is stored in ~/.humalab/config.yaml and includes workspace path,
+    API credentials, and connection settings. Values are automatically loaded on
+    initialization and saved when modified through property setters.
+
+    Attributes:
+        workspace_path (str): The local workspace directory path.
+        base_url (str): The HumaLab API base URL.
+        api_key (str): The API key for authentication.
+        timeout (float): Request timeout in seconds.
+    """
     def __init__(self):
         self._config = {
             "workspace_path": "",
@@ -17,6 +29,7 @@ class HumalabConfig:
         self._load_config()
 
     def _load_config(self):
+        """Load configuration from ~/.humalab/config.yaml."""
         home_path = Path.home()
         config_path = home_path / ".humalab" / "config.yaml"
         if not config_path.exists():
@@ -30,10 +43,16 @@ class HumalabConfig:
         self._timeout = self._config["timeout"] if self._config and "timeout" in self._config else 30.0
 
     def _save(self) -> None:
+        """Save current configuration to ~/.humalab/config.yaml."""
         yaml.dump(self._config, open(Path.home() / ".humalab" / "config.yaml", "w"))
 
     @property
     def workspace_path(self) -> str:
+        """The local workspace directory path.
+
+        Returns:
+            str: The workspace path.
+        """
         return str(self._workspace_path)
     
     @workspace_path.setter
@@ -44,30 +63,60 @@ class HumalabConfig:
 
     @property
     def base_url(self) -> str:
+        """The HumaLab API base URL.
+
+        Returns:
+            str: The base URL.
+        """
         return str(self._base_url)
 
     @base_url.setter
     def base_url(self, base_url: str) -> None:
+        """Set the HumaLab API base URL and save to config.
+
+        Args:
+            base_url (str): The new base URL.
+        """
         self._base_url = base_url
         self._config["base_url"] = base_url
         self._save()
 
     @property
     def api_key(self) -> str:
+        """The API key for authentication.
+
+        Returns:
+            str: The API key.
+        """
         return str(self._api_key)
 
     @api_key.setter
     def api_key(self, api_key: str) -> None:
+        """Set the API key and save to config.
+
+        Args:
+            api_key (str): The new API key.
+        """
         self._api_key = api_key
         self._config["api_key"] = api_key
         self._save()
 
     @property
     def timeout(self) -> float:
+        """Request timeout in seconds.
+
+        Returns:
+            float: The timeout value.
+        """
         return self._timeout
 
     @timeout.setter
     def timeout(self, timeout: float) -> None:
+        """Set the request timeout and save to config.
+
+        Args:
+            timeout (float): The new timeout in seconds.
+        """
         self._timeout = timeout
         self._config["timeout"] = timeout
         self._save()

humalab/metrics/__init__.py

@@ -1,3 +1,9 @@
+"""Metrics tracking and management.
+
+This module provides classes for tracking various types of metrics during runs and episodes,
+including general metrics, summary statistics, code artifacts, and scenario statistics.
+"""
+
 from .metric import Metrics
 from .code import Code
 from .scenario_stats import ScenarioStats

humalab/metrics/code.py

@@ -1,7 +1,18 @@
 class Code:
-    """Class for logging code artifacts."""
-    def __init__(self, 
-                 run_id: str, 
+    """Class for logging code artifacts.
+
+    Code artifacts capture source code or configuration files associated with
+    runs or episodes. They are stored as text content and can be retrieved later
+    for reproducibility and debugging purposes.
+
+    Attributes:
+        run_id (str): The unique identifier of the associated run.
+        key (str): The artifact key/name for this code.
+        code_content (str): The actual code or text content.
+        episode_id (str | None): Optional episode identifier if scoped to an episode.
+    """
+    def __init__(self,
+                 run_id: str,
                  key: str,
                  code_content: str,
                  episode_id: str | None = None) -> None:
@@ -13,16 +24,36 @@ class Code:
 
     @property
     def run_id(self) -> str:
+        """The unique identifier of the associated run.
+
+        Returns:
+            str: The run ID.
+        """
         return self._run_id
-    
+
     @property
     def key(self) -> str:
+        """The artifact key/name for this code.
+
+        Returns:
+            str: The artifact key.
+        """
         return self._key
-    
+
     @property
     def code_content(self) -> str:
+        """The actual code or text content.
+
+        Returns:
+            str: The code content.
+        """
         return self._code_content
-    
+
     @property
     def episode_id(self) -> str | None:
+        """Optional episode identifier if scoped to an episode.
+
+        Returns:
+            str | None: The episode ID, or None if run-scoped.
+        """
         return self._episode_id

humalab/metrics/metric.py

@@ -1,36 +1,70 @@
 from typing import Any
 from humalab.constants import MetricDimType, GraphType
 
+GRAPH_TO_DIM_TYPE = {
+    GraphType.NUMERIC: MetricDimType.ZERO_D,
+    GraphType.LINE: MetricDimType.ONE_D,
+    GraphType.HISTOGRAM: MetricDimType.ONE_D,
+    GraphType.BAR: MetricDimType.ONE_D,
+    GraphType.GAUSSIAN: MetricDimType.ONE_D,
+    GraphType.SCATTER: MetricDimType.TWO_D,
+    GraphType.HEATMAP: MetricDimType.TWO_D,
+    GraphType.THREE_D_MAP: MetricDimType.THREE_D,
+}
+
 
 class Metrics:
+    """Base class for tracking and logging metrics during runs and episodes.
+
+    Metrics provide a flexible way to log time-series data or aggregated values
+    during experiments. Data points are collected with optional x-axis values
+    and can be visualized using different graph types.
+
+    Subclasses should override _finalize() to implement custom processing logic.
+
+    Attributes:
+        graph_type (GraphType): The type of graph used for visualization.
+    """
     def __init__(self,
-                 metric_dim_type: MetricDimType= MetricDimType.ONE_D,
                  graph_type: GraphType=GraphType.LINE) -> None:
-        """
-        Base class for different types of metrics.
+        """Initialize a new Metrics instance.
+
+        Args:
+            graph_type (GraphType): The type of graph to use for visualization
+                (e.g., LINE, BAR, HISTOGRAM, SCATTER). Defaults to LINE.
         """
         self._values = []
         self._x_values = []
         self._step = -1
-        self._metric_dim_type = metric_dim_type
+        self._metric_dim_type = GRAPH_TO_DIM_TYPE.get(graph_type, MetricDimType.ONE_D)
         self._graph_type = graph_type
 
     @property
     def metric_dim_type(self) -> MetricDimType:
+        """The dimensionality of the metric data.
+
+        Returns:
+            MetricDimType: The metric dimension type.
+        """
         return self._metric_dim_type
-    
+
     @property
     def graph_type(self) -> GraphType:
+        """The type of graph used for visualization.
+
+        Returns:
+            GraphType: The graph type.
+        """
         return self._graph_type
     
     def log(self, data: Any, x: Any = None, replace: bool = False) -> None:
-        """Log a new data point for the metric. The behavior depends on the granularity.    
+        """Log a new data point for the metric.
 
         Args:
             data (Any): The data point to log.
             x (Any | None): The x-axis value associated with the data point.
-                if None, the current step is used.
-            replace (bool): Whether to replace the last logged value.
+                If None, uses an auto-incrementing step counter.
+            replace (bool): Whether to replace the last logged value. Defaults to False.
         """
         if replace:
             self._values[-1] = data