groundhog-hpc 0.5.6__py3-none-any.whl → 0.7.0__py3-none-any.whl

groundhog_hpc/configuration/resolver.py

@@ -19,6 +19,7 @@ PEP 723 metadata sets sharable defaults, decorators customize per-function,
 and call-time overrides allow runtime changes.
 """
 
+import logging
 from pathlib import Path
 from typing import Any
 
@@ -26,14 +27,16 @@ from groundhog_hpc.configuration.defaults import DEFAULT_USER_CONFIG
 from groundhog_hpc.configuration.models import EndpointConfig, EndpointVariant
 from groundhog_hpc.configuration.pep723 import read_pep723
 
+logger = logging.getLogger(__name__)
+
 
 def _merge_endpoint_configs(
     base_endpoint_config: dict, override_config: dict | None = None
 ) -> dict:
-    """Merge endpoint configurations, ensuring worker_init commands are combined.
+    """Merge endpoint configurations, ensuring worker_init and endpoint_setup commands are combined.
 
-    The worker_init field is special-cased: if both configs provide it, they are
-    concatenated with the base's worker_init executed first, followed by the override's.
+    The worker_init and endpoint_setup fields are special-cased: if both configs provide them, they are
+    concatenated with the base's commands executed first, followed by the override's.
     All other fields from override_config simply replace fields from base_endpoint_config.
 
     Args:
@@ -44,10 +47,10 @@ def _merge_endpoint_configs(
         A new merged configuration dict
 
     Example:
-        >>> base = {"worker_init": "pip install uv"}
-        >>> override = {"worker_init": "module load gcc", "cores": 4}
+        >>> base = {"worker_init": "pip install uv", "endpoint_setup": "module load gcc"}
+        >>> override = {"worker_init": "module load python", "endpoint_setup": "module load cuda", "cores": 4}
         >>> _merge_endpoint_configs(base, override)
-        {'worker_init': 'pip install uv\\nmodule load gcc', 'cores': 4}
+        {'worker_init': 'pip install uv\\nmodule load python', 'endpoint_setup': 'module load gcc\\nmodule load cuda', 'cores': 4}
     """
     if not override_config:
         return base_endpoint_config.copy()
@@ -62,6 +65,13 @@ def _merge_endpoint_configs(
         override_init = override_config.pop("worker_init")
         merged["worker_init"] = f"{base_init.strip()}\n{override_init.strip()}\n"
 
+    # Special handling for endpoint_setup: prepend base to override
+    if "endpoint_setup" in override_config and "endpoint_setup" in base_endpoint_config:
+        base_setup = base_endpoint_config["endpoint_setup"]
+        # pop endpoint_setup so update doesn't clobber concatenated value
+        override_setup = override_config.pop("endpoint_setup")
+        merged["endpoint_setup"] = f"{base_setup.strip()}\n{override_setup.strip()}\n"
+
     merged.update(override_config)
     return merged
 
@@ -80,7 +90,7 @@ class ConfigResolver:
     5. Call-time config (.remote(user_endpoint_config={...}))
 
     Special handling:
-    - worker_init commands are concatenated (not replaced) across all layers
+    - worker_init and endpoint_setup commands are concatenated (not replaced) across all layers
     - endpoint field in PEP 723 config can override the endpoint UUID
     - Variants inherit from their base configuration
 
@@ -132,9 +142,12 @@ class ConfigResolver:
             ValidationError: If any config level has invalid fields (e.g., negative walltime)
         """
 
+        logger.debug(f"Resolving config for endpoint: {endpoint_name}")
+
         # Layer 1: Start with DEFAULT_USER_CONFIG
         config = DEFAULT_USER_CONFIG.copy()
         base_name, *variant_path = endpoint_name.split(".")
+        logger.debug(f"Starting with DEFAULT_USER_CONFIG: {config}")
 
         # Layer 2-3: walk base[.variant[.sub]] path hierarchically
         metadata: dict = self._load_pep723_metadata()
@@ -142,8 +155,11 @@ class ConfigResolver:
             metadata.get("tool", {}).get("hog", {}).get(base_name, {}).copy()
         )
         if base_variant:
+            logger.debug(f"Found base config for '{base_name}': {base_variant}")
             EndpointConfig.model_validate(base_variant)
             config["endpoint"] = base_variant.pop("endpoint")
+        else:
+            logger.debug(f"No PEP 723 config found for '{base_name}'")
 
         def _merge_variant_path(
             variant_names: list[str], current_variant: dict, accumulated_config: dict
@@ -164,12 +180,18 @@ class ConfigResolver:
                     + variant_path[: len(variant_path) - len(remaining_names)]
                 )
                 if next_variant is None:
+                    logger.error(f"Variant '{next_name}' not found in '{path_so_far}'")
                     raise ValueError(f"Variant {next_name} not found in {path_so_far}")
                 else:
+                    logger.error(
+                        f"Variant '{next_name}' in '{path_so_far}' is not a valid variant "
+                        f"(expected dict, got {type(next_variant).__name__})"
+                    )
                     raise ValueError(
                         f"Variant {next_name} in {path_so_far} is not a valid variant "
                         f"(expected dict, got {type(next_variant).__name__})"
                     )
+            logger.debug(f"Merging variant '{next_name}' config: {next_variant}")
             return _merge_variant_path(
                 remaining_names, next_variant, accumulated_config
             )
@@ -177,16 +199,22 @@ class ConfigResolver:
         config = _merge_variant_path(variant_path, base_variant, config)
 
         # Layer 4: Merge decorator config
+        if decorator_config:
+            logger.debug(f"Merging decorator config: {decorator_config}")
         config = _merge_endpoint_configs(config, decorator_config)
 
         # Layer 5: Call-time overrides
+        if call_time_config:
+            logger.debug(f"Merging call-time config: {call_time_config}")
         config = _merge_endpoint_configs(config, call_time_config)
 
         # Layer 5 1/2: we want to ensure uv is installed *after* any user
         # worker_init, e.g. activating a conda env, which might impact the
         # templated shell command's ability to `uv.find_uv_bin()`
-        uv_init_config = {"worker_init": "pip show -qq uv || pip install uv"}
+        uv_init_config = {"worker_init": "pip show -qq uv || pip install uv || true"}
         config = _merge_endpoint_configs(config, uv_init_config)
+
+        logger.debug(f"Final resolved config: {config}")
         return config
 
     def _load_pep723_metadata(self) -> dict[str, Any]:

groundhog_hpc/console.py

@@ -173,7 +173,7 @@ def _get_status_display(
         display.append(")", style="dim")
 
     display.append(" | ", style="dim")
-    display.append(spinner.render(current_time))
+    display.append(spinner.render(current_time))  # type: ignore[arg-type]
 
     return display
 

groundhog_hpc/decorators.py

@@ -7,32 +7,49 @@ orchestration.
 
 import functools
 import inspect
-import warnings
+import logging
 from types import FunctionType
 from typing import Any, Callable
 
 from groundhog_hpc.function import Function, Method
 from groundhog_hpc.harness import Harness
 
+logger = logging.getLogger(__name__)
+
 
 def harness() -> Callable[[FunctionType], Harness]:
     """Decorator to mark a function as a local orchestrator harness.
 
+    Harness functions are entry points that coordinate remote function calls.
+    They run locally and can accept parameters passed as CLI arguments.
+
     Harness functions:
-    - Must be called via the CLI: `hog run script.py harness_name`
-    - Cannot accept any arguments
-    - Can call .remote() or .submit() on @hog.function decorated functions
+
+    - Are invoked via the CLI: `hog run script.py [harness_name]`
+    - Can accept parameters, which map to CLI arguments
+    - Can call `.remote()` or `.submit()` on `@hog.function`-decorated functions
 
     Returns:
         A decorator function that wraps the harness
 
     Example:
+        Zero-argument harness:
         ```python
         @hog.harness()
         def main():
             result = my_function.remote("far out, man!")
             return result
         ```
+
+        Parameterized harness:
+        ```python
+        @hog.harness()
+        def train(dataset: str, epochs: int = 10):
+            result = train_model.remote(dataset, epochs)
+            return result
+        ```
+
+        Run with: `hog run script.py train -- my_data --epochs=20`
     """
 
     def decorator(func: FunctionType) -> Harness:
@@ -50,9 +67,11 @@ def function(
     """Decorator to mark a function for remote execution on Globus Compute.
 
     Decorated functions can be:
-    - Called locally: func(args)
-    - Called remotely (blocking): func.remote(args)
-    - Submitted asynchronously: func.submit(args)
+
+    - Called locally: `func(args)`
+    - Called remotely (blocking): `func.remote(args)`
+    - Submitted asynchronously: `func.submit(args)`
+    - Called locally in an isolated environment: `func.local(args)`
 
     Args:
         endpoint: Globus Compute endpoint UUID or named endpoint from
@@ -93,13 +112,15 @@ def method(
 ) -> Callable[[FunctionType], Method]:
     """Decorator to mark a class method for remote execution on Globus Compute.
 
-    Similar to @hog.function() but designed for use as class methods. Provides
-    staticmethod-like semantics - the decorated method does not receive self.
+    Analogous to `@hog.function()` but for use with class methods. Provides
+    staticmethod-like semantics - the decorated method does not receive self or cls.
 
     Decorated methods can be:
-    - Called locally: MyClass.method(args) or obj.method(args)
-    - Called remotely (blocking): obj.method.remote(args)
-    - Submitted asynchronously: obj.method.submit(args)
+
+    - Called locally: `MyClass.method(args)` or `obj.method(args)`
+    - Called remotely (blocking): `MyClass.method.remote(args)`
+    - Submitted asynchronously: `MyClass.method.submit(args)`
+    - Called locally in an isolated environment: `MyClass.method.local(args)`
 
     Args:
         endpoint: Globus Compute endpoint UUID
@@ -126,12 +147,10 @@ def method(
         sig = inspect.signature(func)
         params = list(sig.parameters.keys())
         if params and params[0] in ("self", "cls"):
-            warnings.warn(
+            logger.warning(
                 f"Method '{func.__name__}' has first parameter '{params[0]}', "
                 f"but @hog.method provides staticmethod-like semantics and will not "
-                f"pass the instance or class. Consider removing '{params[0]}' from the signature.",
-                UserWarning,
-                stacklevel=2,
+                f"pass the instance or class. Consider removing '{params[0]}' from the signature."
             )
 
         wrapper = Method(func, endpoint, **user_endpoint_config)

groundhog_hpc/function.py

@@ -10,6 +10,7 @@ as defaults but overridden when calling .remote() or .submit().
 """
 
 import inspect
+import logging
 import os
 import sys
 import tempfile
@@ -30,6 +31,8 @@ from groundhog_hpc.future import GroundhogFuture
 from groundhog_hpc.serialization import deserialize_stdout, serialize
 from groundhog_hpc.utils import prefix_output
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     import globus_compute_sdk
 
@@ -44,13 +47,15 @@ class Function:
     """Wrapper that enables a Python function to be executed remotely on Globus Compute.
 
     Decorated functions can be called in four ways:
-    1. Direct call: func(*args) - executes locally (regular python call)
-    2. Remote call: func.remote(*args) - executes remotely and blocks until complete
-    3. Async submit: func.submit(*args) - executes remotely and returns a Future
-    4. Local subprocess: func.local(*args) - executes locally in a separate process
+
+    1. Direct call: `func(*args)` - executes locally (regular python call)
+    2. Remote call: `func.remote(*args)` - executes remotely and blocks until complete
+    3. Async submit: `func.submit(*args)` - executes remotely and returns a GroundhogFuture
+    4. Local subprocess: `func.local(*args)` - executes locally in a separate process
 
     Attributes:
-        endpoint: Default Globus Compute endpoint UUID or None to use resolved config
+        endpoint: Default Globus Compute endpoint UUID or named endpoint from
+            `[tool.hog.<name>]` PEP 723 metadata, or None to use resolved config
         default_user_endpoint_config: Default endpoint configuration (e.g., worker_init, walltime)
     """
 
@@ -77,10 +82,10 @@ class Function:
         # hatch if users need to set it after the function's been created
         self.walltime: int | float | None = None
 
-        self._local_function: FunctionType = func
+        self._wrapped_function: FunctionType = func
         self._config_resolver: ConfigResolver | None = None
 
-    def __call__(self, *args, **kwargs) -> Any:
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
         """Execute the function locally (not remotely).
 
         Args:
@@ -90,7 +95,7 @@ class Function:
         Returns:
             The result of the local function execution
         """
-        return self._local_function(*args, **kwargs)
+        return self._wrapped_function(*args, **kwargs)
 
     def _get_available_endpoints_from_pep723(self) -> list[str]:
         """Get list of endpoint names defined in PEP 723 [tool.hog.*] sections."""
@@ -111,7 +116,8 @@ class Function:
 
         Args:
             *args: Positional arguments to pass to the function
-            endpoint: Globus Compute endpoint UUID (overrides decorator default)
+            endpoint: Globus Compute endpoint UUID (or named endpoint from
+                `[tool.hog.<name>]` PEP 723 metadata). Replaces decorator default.
             user_endpoint_config: Endpoint configuration dict (merged with decorator default)
             **kwargs: Keyword arguments to pass to the function
 
@@ -124,12 +130,18 @@ class Function:
             PayloadTooLargeError: If serialized arguments exceed 10MB
         """
         # Check if module has been marked as safe for .remote() calls
-        module = sys.modules.get(self._local_function.__module__)
+        module = sys.modules.get(self._wrapped_function.__module__)
         if not getattr(module, "__groundhog_imported__", False):
+            logger.error(
+                f"Import safety check failed for module '{self._wrapped_function.__module__}'"
+            )
             raise ModuleImportError(
-                self._local_function.__name__, "submit", self._local_function.__module__
+                self._wrapped_function.__name__,
+                "submit",
+                self._wrapped_function.__module__,
             )
 
+        logger.debug(f"Preparing to submit function '{self.name}'")
         endpoint = endpoint or self.endpoint
 
         decorator_config = self.default_user_endpoint_config.copy()
@@ -152,13 +164,18 @@ class Function:
             available_endpoints = self._get_available_endpoints_from_pep723()
             if available_endpoints:
                 endpoints_str = ", ".join(f"'{e}'" for e in available_endpoints)
+                logger.error(f"No endpoint specified. Available: {endpoints_str}")
                 raise ValueError(
                     f"No endpoint specified. Available endpoints found in config: {endpoints_str}. "
                     f"Call with endpoint=<name>, or specify a function default endpoint in decorator."
                 )
             else:
+                logger.error("No endpoint specified and none found in config")
                 raise ValueError("No endpoint specified")
 
+        logger.debug(
+            f"Serializing {len(args)} args and {len(kwargs)} kwargs for '{self.name}'"
+        )
         payload = serialize((args, kwargs), use_proxy=False, proxy_threshold_mb=None)
         shell_function = script_to_submittable(
             self.script_path, self.name, payload, walltime=self.walltime
@@ -188,7 +205,8 @@ class Function:
 
         Args:
             *args: Positional arguments to pass to the function
-            endpoint: Globus Compute endpoint UUID (overrides decorator default)
+            endpoint: Globus Compute endpoint UUID (or named endpoint from
+                `[tool.hog.<name>]` PEP 723 metadata). Replaces decorator default.
             user_endpoint_config: Endpoint configuration dict (merged with decorator default)
             **kwargs: Keyword arguments to pass to the function
 
@@ -201,6 +219,7 @@ class Function:
             PayloadTooLargeError: If serialized arguments exceed 10MB
             RemoteExecutionError: If remote execution fails (non-zero exit code)
         """
+        logger.debug(f"Calling remote execution for '{self.name}'")
         future = self.submit(
             *args,
             endpoint=endpoint,
@@ -208,7 +227,9 @@ class Function:
             **kwargs,
         )
         display_task_status(future)
-        return future.result()
+        result = future.result()
+        logger.debug(f"Remote execution of '{self.name}' completed successfully")
+        return result
 
     def local(self, *args: Any, **kwargs: Any) -> Any:
         """Execute the function locally in an isolated subprocess.
@@ -226,12 +247,18 @@ class Function:
             LocalExecutionError: If local execution fails (non-zero exit code)
         """
         # Check if module has been marked as safe for .local() calls
-        module = sys.modules.get(self._local_function.__module__)
+        module = sys.modules.get(self._wrapped_function.__module__)
         if not getattr(module, "__groundhog_imported__", False):
+            logger.error(
+                f"Import safety check failed for module '{self._wrapped_function.__module__}'"
+            )
             raise ModuleImportError(
-                self._local_function.__name__, "local", self._local_function.__module__
+                self._wrapped_function.__name__,
+                "local",
+                self._wrapped_function.__module__,
             )
 
+        logger.debug(f"Executing function '{self.name}' in local subprocess")
         with prefix_output(prefix="[local]", prefix_color="blue"):
             # Create ShellFunction just like we do for remote execution
             payload = serialize((args, kwargs), proxy_threshold_mb=1.0)
@@ -247,6 +274,9 @@ class Function:
                 assert not isinstance(result, dict)
 
                 if result.returncode != 0:
+                    logger.error(
+                        f"Local subprocess failed with exit code {result.returncode}"
+                    )
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if result.stdout:
@@ -259,12 +289,16 @@ class Function:
                 try:
                     user_stdout, deserialized_result = deserialize_stdout(result.stdout)
                 except DeserializationError as e:
+                    logger.error(f"Failed to deserialize local result: {e}")
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if e.user_output:
                         print(e.user_output)
                     raise
                 else:
+                    logger.debug(
+                        f"Local execution of '{self.name}' completed successfully"
+                    )
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if user_stdout:
@@ -290,7 +324,7 @@ class Function:
             return self._script_path
 
         try:
-            source_file = inspect.getfile(self._local_function)
+            source_file = inspect.getfile(self._wrapped_function)
             self._script_path = str(Path(source_file).resolve())
             return self._script_path
         except (TypeError, OSError) as e:
@@ -308,13 +342,13 @@ class Function:
 
     @property
     def name(self) -> str:
-        return self._local_function.__qualname__
+        return self._wrapped_function.__qualname__
 
 
 class Method(Function):
-    """Descriptor variant of Function for use as class methods.
+    """Minimal descriptor variant of Function for use as class methods.
 
-    Provides staticmethod-like semantics (no self) with remote execution.
+    Provides staticmethod-like semantics (no `self`/`cls`) with remote execution.
     """
 
     def __get__(self, obj, objtype=None):

groundhog_hpc/future.py

@@ -22,16 +22,16 @@ else:
 
 class GroundhogFuture(Future):
     """A Future that deserializes stdout for its .result(), but still allows
-    access to the raw ShellResult.
+    access to the raw `ShellResult`.
 
     This future automatically deserializes the payload when .result() is called,
-    but preserves access to the original ShellResult (with stdout, stderr, returncode)
+    but preserves access to the original `ShellResult` (with stdout, stderr, returncode)
     via the .shell_result property.
 
     Attributes:
         task_id: Globus Compute task ID (set when the future completes)
-        endpoint: UUID of the endpoint where the task was submitted
-        user_endpoint_config: Configuration dict used for the endpoint
+        endpoint: The endpoint where the task was submitted
+        user_endpoint_config: Resolved configuration dict used for the endpoint
         function_name: Name of the function being executed
     """
 
@@ -48,9 +48,9 @@ class GroundhogFuture(Future):
         self._user_stdout: str | None = None
 
         # set after created in Function.submit, useful for invocation logs etc
-        self.endpoint: str | None = None
-        self.user_endpoint_config: dict[str, Any] | None = None
-        self.function_name: str | None = None
+        self._endpoint: str | None = None
+        self._user_endpoint_config: dict[str, Any] | None = None
+        self._function_name: str | None = None
 
         def callback(fut: Future) -> None:
             try:
@@ -69,7 +69,7 @@ class GroundhogFuture(Future):
 
     @property
     def shell_result(self) -> ShellResult:
-        """Access the raw ShellResult with stdout, stderr, returncode.
+        """Access the raw Globus Compute `ShellResult` with stdout, stderr, returncode.
 
         This property provides access to the underlying shell execution metadata,
         which can be useful for debugging, logging, or inspecting stderr output
@@ -93,7 +93,45 @@ class GroundhogFuture(Future):
 
     @property
     def task_id(self) -> str | None:
-        return self._original_future.task_id
+        """The Globus Compute task ID for this future.
+
+        Returns the task ID from the underlying Globus Compute future, which may
+        not be populated immediately.
+        """
+        return self._original_future.task_id  # type: ignore[attr-defined]
+
+    @property
+    def endpoint(self) -> str | None:
+        """The endpoint where this task was submitted."""
+        return self._endpoint
+
+    @endpoint.setter
+    def endpoint(self, value: str | None) -> None:
+        self._endpoint = value
+
+    @property
+    def user_endpoint_config(self) -> dict[str, Any] | None:
+        """The endpoint configuration used for this task submission.
+
+        Set by `Function.submit()` when the task is created. Contains
+        configuration like account, partition, walltime, etc. Useful for
+        debugging, since this is the final resolved config that was actually
+        passed to the `Executor`.
+        """
+        return self._user_endpoint_config
+
+    @user_endpoint_config.setter
+    def user_endpoint_config(self, value: dict[str, Any] | None) -> None:
+        self._user_endpoint_config = value
+
+    @property
+    def function_name(self) -> str | None:
+        """The name of the function being executed."""
+        return self._function_name
+
+    @function_name.setter
+    def function_name(self, value: str | None) -> None:
+        self._function_name = value
 
 
 def _truncate_payload_in_cmd(cmd: str, max_length: int = 100) -> str:
@@ -123,7 +161,7 @@ def _truncate_payload_in_cmd(cmd: str, max_length: int = 100) -> str:
 
 
 def _process_shell_result(shell_result: ShellResult) -> tuple[str | None, Any]:
-    """Process a ShellResult by checking for errors and deserializing the result payload.
+    """Process a `ShellResult` by checking for errors and deserializing the result payload.
 
     The stdout contains two parts separated by "__GROUNDHOG_RESULT__":
     1. User output (from the .stdout file) - returned as first element of tuple

groundhog_hpc/harness.py

@@ -1,7 +1,8 @@
 """Harness wrapper for orchestrating remote function execution.
 
-This module provides the Harness class, which wraps zero-argument entry point
-functions that orchestrate calls to remote @hog.function decorated functions.
+This module provides the Harness class, which wraps entry point functions that
+orchestrate calls to remote @hog.function decorated functions. Harnesses can
+accept parameters which are parsed from CLI arguments via `hog run`.
 """
 
 import inspect
@@ -10,13 +11,15 @@ from typing import Any
 
 
 class Harness:
-    """Wrapper for a zero-argument orchestrator function.
+    """Wrapper for an orchestrator function.
 
     Harness functions are entry points that typically coordinate calls to
-    @hog.function decorated functions. They must not accept any arguments.
+    @hog.function decorated functions. They can accept parameters that are
+    parsed from CLI arguments when invoked via `hog run script.py -- args`.
 
     Attributes:
         func: The wrapped orchestrator function
+        signature: The function's signature for CLI argument parsing
     """
 
     def __init__(self, func: FunctionType):
@@ -24,25 +27,18 @@ class Harness:
 
         Args:
             func: The orchestrator function to wrap
-
-        Raises:
-            TypeError: If the function accepts any arguments
         """
         self.func: FunctionType = func
-        self._validate_signature()
+        self.signature: inspect.Signature = inspect.signature(func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the harness function with optional arguments.
 
-    def __call__(self) -> Any:
-        """Execute the harness function.
+        Args:
+            *args: Positional arguments to pass to the harness function
+            **kwargs: Keyword arguments to pass to the harness function
 
         Returns:
             The result of the harness function execution
         """
-        return self.func()
-
-    def _validate_signature(self) -> None:
-        sig = inspect.signature(self.func)
-        if len(sig.parameters) > 0:
-            raise TypeError(
-                f"Harness function '{self.func.__qualname__}' must not accept any arguments, "
-                f"but has parameters: {list(sig.parameters.keys())}"
-            )
+        return self.func(*args, **kwargs)

groundhog_hpc/logging.py

@@ -0,0 +1,51 @@
+"""Logging configuration for Groundhog HPC.
+
+This module provides centralized logging setup with support for:
+- Hierarchical per-module loggers (groundhog.compute, groundhog.serialization, etc.)
+- Environment variable configuration (GROUNDHOG_LOG_LEVEL)
+- CLI flag overrides
+- Remote log level propagation
+"""
+
+import logging
+import os
+import sys
+
+
+def setup_logging() -> None:
+    """Configure the root groundhog logger.
+
+    Reads log level from GROUNDHOG_LOG_LEVEL environment variable.
+    Defaults to WARNING if not set.
+
+    Valid log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
+
+    Can be called multiple times to reconfigure the log level.
+    """
+    level_name = os.getenv("GROUNDHOG_LOG_LEVEL", "WARNING").upper()
+
+    # Convert string to logging level, default to WARNING if invalid
+    level = getattr(logging, level_name, logging.WARNING)
+
+    # Configure root groundhog logger
+    logger = logging.getLogger("groundhog_hpc")
+    logger.setLevel(level)
+
+    # Add stderr handler if not already present
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+    else:
+        # Update level on existing handlers
+        for handler in logger.handlers:
+            handler.setLevel(level)
+
+    # Allow propagation to parent loggers (enables pytest caplog capture)
+    # This won't cause duplicate logs unless the root logger also has handlers,
+    # which is rare in production but common in tests
+    logger.propagate = True