zoo-runner-common 0.1.1__py3-none-any.whl

base_runner.py

@@ -0,0 +1,334 @@
+import logging
+import os
+import sys
+import traceback
+import types
+from abc import ABC, abstractmethod
+
+# Shared ZooStub import
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), ".")))
+
+try:
+    import zoo
+except ImportError:
+    from zoostub import ZooStub
+
+    zoo = ZooStub()
+
+from zoo_conf import CWLWorkflow, ZooConf, ZooInputs, ZooOutputs
+
+logger = logging.getLogger()
+
+
+class BaseRunner(ABC):
+    """
+    Base class for CWL workflow runners.
+    Provides common functionality and defines the interface for specific runners.
+    """
+
+    def __init__(self, cwl, inputs, conf, outputs, execution_handler=None):
+        """
+        Initialize the base runner.
+
+        :param cwl: CWL workflow definition (path to file or parsed CWL)
+        :param inputs: ZOO inputs dictionary
+        :param conf: ZOO configuration dictionary
+        :param outputs: ZOO outputs dictionary
+        :param execution_handler: Optional ExecutionHandler instance for hooks
+        """
+        self.cwl = cwl
+        self.execution_handler = execution_handler or self._create_default_handler()
+
+        # Create typed wrapper objects from ZOO dictionaries
+        self.conf = ZooConf(conf)
+        self.inputs = ZooInputs(inputs)
+        self.outputs = ZooOutputs(outputs)
+
+        # Parse CWL workflow
+        self.workflow = CWLWorkflow(self.cwl, self.conf.workflow_id)
+
+        # Legacy namespace for backward compatibility
+        self.zoo_conf = types.SimpleNamespace(conf=conf)
+
+        # Runner-specific state
+        self.namespace_name = None
+        self.execution = None
+
+    def _create_default_handler(self):
+        """Create a default handler if none provided."""
+
+        class DefaultHandler:
+            def pre_execution_hook(self):
+                pass
+
+            def post_execution_hook(self, *args, **kwargs):
+                pass
+
+            def get_secrets(self):
+                return None
+
+            def get_additional_parameters(self):
+                return {}
+
+            def get_pod_env_vars(self):
+                return None
+
+            def get_pod_node_selector(self):
+                return None
+
+            def handle_outputs(self, *args, **kwargs):
+                pass
+
+            def set_job_id(self, job_id):
+                pass
+
+            def get_namespace(self):
+                """Get namespace for Calrissian execution."""
+                return None
+
+            def get_service_account(self):
+                """Get service account for Calrissian execution."""
+                return None
+
+        return DefaultHandler()
+
+    def update_status(self, progress: int, message: str = ""):
+        """
+        Update execution status in ZOO.
+
+        Args:
+            progress: Progress percentage (0-100)
+            message: Status message to display
+        """
+        if hasattr(self.conf, 'conf') and "lenv" in self.conf.conf:
+            self.conf.conf["lenv"]["message"] = message
+            zoo.update_status(self.conf.conf, progress)
+        else:
+            logger.warning("Cannot update status: conf structure not available")
+
+    def get_namespace_name(self):
+        """
+        Generate a namespace name for Kubernetes resources.
+
+        Returns:
+            str: Namespace name in format {workflow_id}-{unique_id}
+        """
+        if self.namespace_name is None:
+            import uuid
+            unique_id = str(uuid.uuid4())[:8]
+            self.namespace_name = f"{self.get_workflow_id()}-{unique_id}".lower()
+
+        return self.namespace_name
+
+    def log_output(self, output):
+        """Log output information."""
+        logger.info("[BaseRunner] Output: %s", output)
+
+    def validate_inputs(self):
+        """Validate input parameters."""
+        logger.info("[BaseRunner] Validating inputs...")
+        return True
+
+    def prepare(self):
+        """
+        Shared pre-execution logic.
+        Calls execution handler hooks and prepares processing parameters.
+        """
+        logger.info("execution started")
+        self.update_status(progress=2, message="starting execution")
+
+        # Call pre-execution hook
+        if self.execution_handler and hasattr(
+            self.execution_handler, "pre_execution_hook"
+        ):
+            try:
+                self.execution_handler.pre_execution_hook()
+            except Exception as e:
+                logger.error(f"Error in pre_execution_hook: {e}")
+                logger.error(traceback.format_exc())
+                raise
+
+        logger.info("wrap CWL workflow with stage-in/out steps")
+
+        processing_parameters = {
+            **self.get_processing_parameters(),
+            **(
+                self.execution_handler.get_additional_parameters()
+                if self.execution_handler
+                else {}
+            ),
+        }
+
+        return types.SimpleNamespace(cwl=self.wrap(), params=processing_parameters)
+
+    def finalize(self, log, output, usage_report, tool_logs):
+        """
+        Finalization logic after execution.
+        Calls execution handler post-execution and output handling hooks.
+        """
+        logger.info("Finalization started")
+
+        # Call post-execution hook
+        if self.execution_handler and hasattr(
+            self.execution_handler, "post_execution_hook"
+        ):
+            try:
+                self.execution_handler.post_execution_hook(
+                    log, output, usage_report, tool_logs
+                )
+            except Exception as e:
+                logger.error(f"Error in post_execution_hook: {e}")
+                logger.error(traceback.format_exc())
+                raise
+
+        # Call handle_outputs hook
+        if self.execution_handler and hasattr(self.execution_handler, "handle_outputs"):
+            try:
+                self.execution_handler.handle_outputs(
+                    log, output, usage_report, tool_logs
+                )
+            except Exception as e:
+                logger.error(f"Error in handle_outputs: {e}")
+                logger.error(traceback.format_exc())
+                raise
+
+    def get_workflow_id(self):
+        """
+        Get the workflow identifier from configuration.
+
+        Returns:
+            str: The workflow identifier
+        """
+        return self.conf.workflow_id
+
+    def get_workflow_inputs(self, mandatory=False):
+        """
+        Get workflow input parameter names.
+
+        Args:
+            mandatory: If True, only return mandatory inputs (no default value)
+
+        Returns:
+            list: List of input parameter names
+        """
+        return self.workflow.get_workflow_inputs(mandatory=mandatory)
+
+    def get_max_cores(self):
+        """
+        Get the maximum number of cores from CWL ResourceRequirements.
+
+        Returns:
+            int: Maximum cores requested, or default from environment
+        """
+        resources = self.workflow.eval_resource()
+        max_cores = max(resources["coresMax"]) if resources["coresMax"] else None
+
+        if max_cores is None:
+            max_cores = int(os.environ.get("DEFAULT_MAX_CORES", "2"))
+
+        return max_cores
+
+    def get_max_ram(self):
+        """
+        Get the maximum RAM in megabytes from CWL ResourceRequirements.
+
+        Returns:
+            str: Maximum RAM in MB with unit (e.g., "4096Mi")
+        """
+        resources = self.workflow.eval_resource()
+        max_ram = max(resources["ramMax"]) if resources["ramMax"] else None
+
+        if max_ram is None:
+            max_ram = int(os.environ.get("DEFAULT_MAX_RAM", "4096"))
+
+        # Return as string with Mi unit
+        return f"{max_ram}Mi"
+
+    def get_volume_size(self, unit="Mi"):
+        """
+        Get the volume size for temporary and output directories.
+
+        Calculates based on tmpdir and outdir requirements from CWL.
+
+        Args:
+            unit: Unit for volume size ('Gi' for Gigabytes or 'Mi' for Megabytes)
+
+        Returns:
+            str: Volume size with unit (e.g., "10Gi" or "10240Mi")
+        """
+        resources = self.workflow.eval_resource()
+
+        # Get max tmpdir and outdir in MB
+        # Use Max if available, otherwise fall back to Min
+        tmpdir_max = max(resources["tmpdirMax"]) if resources["tmpdirMax"] else (max(resources["tmpdirMin"]) if resources["tmpdirMin"] else 0)
+        outdir_max = max(resources["outdirMax"]) if resources["outdirMax"] else (max(resources["outdirMin"]) if resources["outdirMin"] else 0)
+
+        # Total in MB
+        volume_size_mb = tmpdir_max + outdir_max
+
+        if volume_size_mb == 0:
+            # Default from environment
+            default = os.environ.get("DEFAULT_VOLUME_SIZE", "10Gi")
+            # If default doesn't match requested unit, convert
+            if unit not in default:
+                return f"10{unit}"
+            return default
+
+        # Convert based on requested unit
+        if unit == "Gi":
+            # Convert MB to Gi (1 Gi = 1024 Mi)
+            volume_size = int(volume_size_mb / 1024) + 1
+        else:  # Mi
+            volume_size = volume_size_mb
+
+        return f"{volume_size}{unit}"
+
+    def assert_parameters(self, mandatory=True):
+        """
+        Validate that required workflow inputs are provided.
+
+        Args:
+            mandatory: If True, check only mandatory inputs
+
+        Returns:
+            bool: True if all required inputs are present, False otherwise
+        """
+        try:
+            required_inputs = self.get_workflow_inputs(mandatory=mandatory)
+
+            for required_input in required_inputs:
+                if required_input not in self.inputs.inputs:
+                    error_msg = f"Missing required input: {required_input}"
+                    logger.error(error_msg)
+                    return False
+
+            logger.info("All required parameters are present")
+            return True
+        except Exception as e:
+            logger.error(f"Error checking parameters: {e}")
+            return False
+
+    def get_processing_parameters(self):
+        """
+        Get processing parameters from inputs.
+
+        Returns:
+            dict: Processing parameters suitable for CWL execution
+        """
+        return self.inputs.get_processing_parameters(workflow=self.workflow.get_workflow())
+
+    @abstractmethod
+    def wrap(self):
+        """
+        Wrap the CWL workflow with stage-in/stage-out steps.
+        Must be implemented by subclasses.
+        """
+        raise NotImplementedError("Subclasses must implement wrap()")
+
+    @abstractmethod
+    def execute(self):
+        """
+        Execute the CWL workflow.
+        Must be implemented by subclasses.
+        """
+        raise NotImplementedError("Subclasses must implement execute()")

zoo_conf.py

@@ -0,0 +1,317 @@
+import inspect
+import os
+
+import attr
+import cwl_utils
+from cwl_utils.parser import load_document_by_yaml
+
+
+# useful class for hints in CWL
+@attr.s
+class ResourceRequirement:
+    coresMin = attr.ib(default=None)
+    coresMax = attr.ib(default=None)
+    ramMin = attr.ib(default=None)
+    ramMax = attr.ib(default=None)
+    tmpdirMin = attr.ib(default=None)
+    tmpdirMax = attr.ib(default=None)
+    outdirMin = attr.ib(default=None)
+    outdirMax = attr.ib(default=None)
+
+    @classmethod
+    def from_dict(cls, env):
+        return cls(
+            **{k: v for k, v in env.items() if k in inspect.signature(cls).parameters}
+        )
+
+
+class CWLWorkflow:
+    def __init__(self, cwl, workflow_id):
+        self.raw_cwl = cwl
+        self.workflow_id = workflow_id
+        
+        # Load the entire CWL document and convert to v1.2
+        # Use load_cwl_from_yaml instead of load_document_by_yaml for proper version conversion
+        from cwl_loader import load_cwl_from_yaml
+        
+        parsed_cwl = load_cwl_from_yaml(cwl, uri="io://", cwl_version='v1.2', sort=True)
+
+        # Ensure self.cwl is always a list containing all CWL elements
+        if not isinstance(parsed_cwl, list):
+            parsed_cwl = [parsed_cwl]
+
+        self.cwl = parsed_cwl
+
+    def get_version(self):
+
+        return self.raw_cwl.get("s:softwareVersion", "")
+
+    def get_label(self):
+
+        return self.get_workflow().label
+
+    def get_doc(self):
+
+        return self.get_workflow().doc
+
+    def get_workflow(self) -> cwl_utils.parser.cwl_v1_0.Workflow:
+        # returns a cwl_utils.parser.cwl_v1_0.Workflow)
+        ids = [elem.id.split("#")[-1] for elem in self.cwl]
+
+        return self.cwl[ids.index(self.workflow_id)]
+
+    def get_object_by_id(self, id):
+        ids = [elem.id.split("#")[-1] for elem in self.cwl]
+        # Remove leading '#' if present, and also remove 'io://' prefix if present
+        search_id = id.lstrip("#").replace("io://", "")
+        return self.cwl[ids.index(search_id)]
+
+    def get_workflow_inputs(self, mandatory=False):
+        inputs = []
+        for inp in self.get_workflow().inputs:
+            if mandatory:
+                # Use type_ instead of type (cwl-utils API change)
+                inp_type = getattr(inp, 'type_', getattr(inp, 'type', None))
+                if inp.default is not None or inp_type == ["null", "string"]:
+                    continue
+                else:
+                    inputs.append(inp.id.split("/")[-1])
+            else:
+                inputs.append(inp.id.split("/")[-1])
+        return inputs
+
+    @staticmethod
+    def has_scatter_requirement(workflow):
+        return any(
+            isinstance(
+                requirement,
+                (
+                    cwl_utils.parser.cwl_v1_0.ScatterFeatureRequirement,
+                    cwl_utils.parser.cwl_v1_1.ScatterFeatureRequirement,
+                    cwl_utils.parser.cwl_v1_2.ScatterFeatureRequirement,
+                ),
+            )
+            for requirement in workflow.requirements
+        )
+
+    @staticmethod
+    def get_resource_requirement(elem):
+        """Gets the ResourceRequirement out of a CommandLineTool or Workflow
+
+        Args:
+            elem (CommandLineTool or Workflow): CommandLineTool or Workflow
+
+        Returns:
+            cwl_utils.parser.cwl_v1_2.ResourceRequirement or ResourceRequirement
+        """
+        resource_requirement = []
+
+        # look for requirements
+        if elem.requirements is not None:
+            resource_requirement = [
+                requirement
+                for requirement in elem.requirements
+                if isinstance(
+                    requirement,
+                    (
+                        cwl_utils.parser.cwl_v1_0.ResourceRequirement,
+                        cwl_utils.parser.cwl_v1_1.ResourceRequirement,
+                        cwl_utils.parser.cwl_v1_2.ResourceRequirement,
+                    ),
+                )
+            ]
+
+            if len(resource_requirement) == 1:
+                return resource_requirement[0]
+
+        # look for hints
+        if elem.hints is not None:
+            resource_requirement = []
+            for hint in elem.hints:
+                # Handle both dict and object types
+                if isinstance(hint, dict):
+                    if hint.get("class") == "ResourceRequirement":
+                        resource_requirement.append(ResourceRequirement.from_dict(hint))
+                elif hasattr(hint, 'class_'):
+                    if hint.class_ == "ResourceRequirement":
+                        resource_requirement.append(hint)
+
+            if len(resource_requirement) == 1:
+                return resource_requirement[0]
+
+    def eval_resource(self):
+        resources = {
+            "coresMin": [],
+            "coresMax": [],
+            "ramMin": [],
+            "ramMax": [],
+            "tmpdirMin": [],
+            "tmpdirMax": [],
+            "outdirMin": [],
+            "outdirMax": [],
+        }
+
+        for elem in self.cwl:
+            if isinstance(
+                elem,
+                (
+                    cwl_utils.parser.cwl_v1_0.Workflow,
+                    cwl_utils.parser.cwl_v1_1.Workflow,
+                    cwl_utils.parser.cwl_v1_2.Workflow,
+                ),
+            ):
+                if resource_requirement := self.get_resource_requirement(elem):
+                    for resource_type in [
+                        "coresMin",
+                        "coresMax",
+                        "ramMin",
+                        "ramMax",
+                        "tmpdirMin",
+                        "tmpdirMax",
+                        "outdirMin",
+                        "outdirMax",
+                    ]:
+                        if getattr(resource_requirement, resource_type):
+                            resources[resource_type].append(
+                                getattr(resource_requirement, resource_type)
+                            )
+                for step in elem.steps:
+                    if resource_requirement := self.get_resource_requirement(
+                        self.get_object_by_id(step.run[1:])
+                    ):
+                        multiplier = (
+                            int(os.getenv("SCATTER_MULTIPLIER", 2))
+                            if step.scatter
+                            else 1
+                        )
+                        for resource_type in [
+                            "coresMin",
+                            "coresMax",
+                            "ramMin",
+                            "ramMax",
+                            "tmpdirMin",
+                            "tmpdirMax",
+                            "outdirMin",
+                            "outdirMax",
+                        ]:
+                            if getattr(resource_requirement, resource_type):
+                                resources[resource_type].append(
+                                    getattr(resource_requirement, resource_type)
+                                    * multiplier
+                                )
+        return resources
+
+
+class ZooConf:
+    def __init__(self, conf):
+        self.conf = conf
+        self.workflow_id = self.conf["lenv"]["Identifier"]
+
+
+class ZooInputs:
+    def __init__(self, inputs):
+        # this conversion is necessary
+        # because zoo converts array of length 1 to a string
+        for inp in inputs:
+            if (
+                "maxOccurs" in inputs[inp].keys()
+                and int(inputs[inp]["maxOccurs"]) > 1
+                and not isinstance(inputs[inp]["value"], list)
+            ):
+                inputs[inp]["value"] = [inputs[inp]["value"]]
+
+        self.inputs = inputs
+
+    def get_input_value(self, key):
+        try:
+            return self.inputs[key]["value"]
+        except KeyError as exc:
+            raise exc
+        except TypeError:
+            pass
+
+    def get_processing_parameters(self, workflow=None):
+        """Returns a list with the input parameters keys
+        
+        Args:
+            workflow: Optional CWL workflow object (currently unused, for future compatibility)
+        """
+        import json
+        
+        res = {}
+        allowed_types = ["integer", "float", "boolean", "double"]
+        
+        for key, value in self.inputs.items():
+            if "format" in value and not("dataType" in value and value["dataType"] in allowed_types):
+                res[key] = {
+                    "format": value["format"],
+                    "value": value["value"],
+                }
+            elif "dataType" in value:
+                if isinstance(value["dataType"], list):
+                    if value["dataType"][0] in allowed_types:
+                        if value["dataType"][0] in ["double", "float"]:
+                            res[key] = [float(item) for item in value["value"]]
+                        elif value["dataType"][0] == "integer":
+                            res[key] = [int(item) for item in value["value"]]
+                        elif value["dataType"][0] == "boolean":
+                            res[key] = [bool(item) for item in value["value"]]
+                    else:
+                        res[key] = value["value"]
+                else:
+                    if value["value"] == "NULL":
+                        res[key] = None
+                    else:
+                        if value["dataType"] in ["double", "float"]:
+                            res[key] = float(value["value"])
+                        elif value["dataType"] == "integer":
+                            res[key] = int(value["value"])
+                        elif value["dataType"] == "boolean":
+                            res[key] = bool(value["value"])
+                        else:
+                            res[key] = value["value"]
+            else:
+                if "cache_file" in value:
+                    if "isArray" in value and value["isArray"] == "true":
+                        res[key] = []
+                        for i in range(len(value["value"])):
+                            res[key].append({
+                                "format": value["mimeType"][i] if "mimeType" in value else "text/plain",
+                                "value": value["value"][i],
+                            })
+                    else:
+                        res[key] = {
+                            "format": value.get("mimeType", "text/plain"),
+                            "value": value["value"]
+                        }
+                else:
+                    if "lowerCorner" in value and "upperCorner" in value:
+                        res[key] = {
+                            "format": "ogc-bbox",
+                            "bbox": json.loads(value["value"]),
+                            "crs": value["crs"].replace("http://www.opengis.net/def/crs/OGC/1.3/", "")
+                        }
+                    else:
+                        res[key] = value["value"]
+        return res
+
+
+class ZooOutputs:
+    def __init__(self, outputs):
+        self.outputs = outputs
+        # decuce the output key
+        output_keys = list(self.outputs.keys())
+        if len(output_keys) > 0:
+            self.output_key = output_keys[0]
+        else:
+            self.output_key = "stac"
+            if "stac" not in self.outputs.keys():
+                self.outputs["stac"] = {}
+
+    def get_output_parameters(self):
+        """Returns a list with the output parameters keys"""
+        return {key: value["value"] for key, value in self.outputs.items()}
+
+    def set_output(self, value):
+        """set the output result value"""
+        self.outputs[self.output_key]["value"] = value

zoo_runner_common-0.1.1.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: zoo-runner-common
+Version: 0.1.1
+Summary: Shared utilities for ZOO-Project CWL runners
+Author-email: Aryan Khare <kharearyan78@gmail.com>, Gérald Fenoy <gerald.fenoy@geolabs.fr>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/ZOO-Project/zoo-runner-common
+Project-URL: Documentation, https://zoo-project.github.io/zoo-runner-common/
+Project-URL: Repository, https://github.com/ZOO-Project/zoo-runner-common
+Project-URL: Issues, https://github.com/ZOO-Project/zoo-runner-common/issues
+Project-URL: Changelog, https://github.com/ZOO-Project/zoo-runner-common/blob/main/CHANGELOG.md
+Keywords: zoo-project,cwl,runner,workflow,ogc,api,processes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: loguru>=0.7.0
+
+# zoo-runner-common
+
+A shared utility library for ZOO-Project CWL runners – centralizing reusable components across runners like **Calrissian**, **Argo Workflows**, and **WES**.
+
+---
+
+## Overview
+
+The `zoo-runner-common` repository provides core shared components used across multiple ZOO CWL runners. It **eliminates code duplication** by hosting:
+
+- **Common base class** (`BaseRunner`) with 8+ shared methods
+- **Zoo-specific configuration handlers** (`ZooConf`, `ZooInputs`, `ZooOutputs`)
+- **CWL workflow parsing** and resource evaluation (`CWLWorkflow`)
+- **Execution handler interface** (`ExecutionHandler`) for hooks
+- **Service stubs** (`ZooStub`) to communicate with ZOO kernel
+
+### Key Benefits
+
+- ✅ **~437 lines of code duplication eliminated** across 3 runners
+- ✅ **Single source of truth** for common functionality
+- ✅ **Easier maintenance** - fix once, benefit everywhere
+- ✅ **Consistent behavior** across all runners
+
+---
+
+## Directory Structure
+
+```
+zoo-runner-common/
+├── base_runner.py      # Abstract BaseRunner with common methods
+├── zoo_conf.py         # ZooConf, ZooInputs, ZooOutputs, CWLWorkflow
+├── handlers.py         # ExecutionHandler abstract base class
+├── zoostub.py          # ZooStub for ZOO kernel communication
+└── __init__.py         # Package initialization
+```
+
+---
+
+## Installation
+
+### As a dependency (recommended)
+
+Add to your runner's `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "zoo-runner-common @ git+https://github.com/ZOO-Project/zoo-runner-common.git@main",
+]
+```
+
+### Local development
+
+```bash
+export PYTHONPATH="$PYTHONPATH:/path/to/zoo-runner-common"
+```
+
+Or use relative imports:
+
+```python
+import sys
+sys.path.insert(0, os.path.abspath('../zoo-runner-common'))
+from base_runner import BaseRunner
+from zoo_conf import ZooConf, ZooInputs, ZooOutputs, CWLWorkflow
+from handlers import ExecutionHandler
+```
+
+---
+
+## Components
+
+### BaseRunner (base_runner.py)
+
+Abstract base class providing common functionality for all CWL runners:
+
+**Methods provided:**
+- `get_workflow_id()` - Get workflow identifier
+- `get_workflow_inputs(mandatory=False)` - Get workflow input parameters
+- `get_max_cores()` - Get maximum CPU cores from CWL
+- `get_max_ram()` - Get maximum RAM from CWL
+- `get_volume_size(unit='Gi')` - Calculate volume size (supports Mi/Gi)
+- `assert_parameters(mandatory=True)` - Validate required inputs
+- `get_processing_parameters()` - Get execution parameters
+- `get_namespace_name()` - Generate unique namespace name
+- `update_status(progress, message)` - Update execution status
+- `prepare()` - Pre-execution preparation with hooks
+- `finalize(log, output, usage_report, tool_logs)` - Post-execution finalization
+
+**Abstract methods (to implement):**
+- `wrap()` - Wrap CWL with stage-in/stage-out
+- `execute()` - Execute the workflow
+
+### Zoo Configuration Classes (zoo_conf.py)
+
+| Class | Description |
+|-------|-------------|
+| `ZooConf` | Wraps ZOO configuration dictionary |
+| `ZooInputs` | Handles input parameter conversion and validation |
+| `ZooOutputs` | Manages output parameters |
+| `CWLWorkflow` | Parses CWL, evaluates resources, handles scatter |
+| `ResourceRequirement` | CWL resource hints dataclass |
+
+**Key Features:**
+- Advanced type conversion (int, float, bool, arrays)
+- File handling with format metadata
+- OGC bounding box support
+- NULL value handling
+- Array inputs with `isArray`
+
+### ExecutionHandler (handlers.py)
+
+Abstract base class for execution customization:
+
+```python
+class ExecutionHandler(ABC):
+    @abstractmethod
+    def pre_execution_hook(self): pass
+    
+    @abstractmethod
+    def post_execution_hook(self, log, output, usage_report, tool_logs): pass
+    
+    @abstractmethod
+    def get_secrets(self): pass
+    
+    @abstractmethod
+    def get_pod_env_vars(self): pass
+    
+    @abstractmethod
+    def get_pod_node_selector(self): pass
+    
+    @abstractmethod
+    def handle_outputs(self, log, output, usage_report, tool_logs): pass
+    
+    @abstractmethod
+    def get_additional_parameters(self): pass
+```
+
+---
+
+## Usage Example
+
+```python
+from zoo_runner_common.base_runner import BaseRunner
+from zoo_runner_common.handlers import ExecutionHandler
+
+class MyCustomRunner(BaseRunner):
+    def wrap(self):
+        # Implement CWL wrapping logic
+        return wrapped_cwl
+    
+    def execute(self):
+        # Prepare execution
+        cwljob = self.prepare()
+        
+        # Execute workflow (custom logic)
+        result = my_executor.run(cwljob.cwl, cwljob.params)
+        
+        # Finalize
+        self.finalize(log, output, usage_report, tool_logs)
+        return result
+```
+
+---
+
+## Runners Using zoo-runner-common
+
+| Runner | Backend | Repository |
+|--------|---------|------------|
+| **zoo-calrissian-runner** | Calrissian/Kubernetes | [EOEPCA/zoo-calrissian-runner](https://github.com/EOEPCA/zoo-calrissian-runner) |
+| **zoo-argowf-runner** | Argo Workflows | [ZOO-Project/zoo-argowf-runner](https://github.com/ZOO-Project/zoo-argowf-runner) |
+| **zoo-wes-runner** | WES/TOIL | [ZOO-Project/zoo-wes-runner](https://github.com/ZOO-Project/zoo-wes-runner) |
+
+---
+
+## Module Reference
+
+| Module |	Description |
+| ---- | -------- |
+| BaseRunner |	Abstract runner blueprint all runners must extend |
+| ZooConf |	Parses conf.json, manages job ID, state |
+| ZooInputs |	Parses inputs.json, formats CWL-style parameters |
+| ZooOutputs |	Handles writing and setting output results |
+| CWLWorkflow |	Loads, parses, and analyzes CWL workflows |
+| ResourceRequirement |	Parses and evaluates CWL resource hints/requirements |
+| wrapper_utils |	Provides helper to build wrapped CWL pipeline |
+| ZooStub |	Interacts with ZOO's lenv for progress updates |
+
+---
+
+## Used By
+- zoo-wes-runner
+- zoo-argowf-runner
+- zoo-calrissian-runner

zoo_runner_common-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+base_runner.py,sha256=DF7BE_UHgILhxY-zNxCAjOkYqR5mzAmy6I9dZgo0Qqs,10674
+zoo_conf.py,sha256=WD7-wRCogxDvIhRN2m8ILCwHPm3JdlsqNnFj6F1sH3o,11655
+zoostub.py,sha256=6c0VClH9MjkOxpCaA1z8Kf_cIP3k4k0nBWkGxhN2mAY,926
+zoo_runner_common-0.1.1.dist-info/METADATA,sha256=QyS2m7_aWtm8gQf6vBmtXmwiDFduRq-qnjZ67uvAvaE,7001
+zoo_runner_common-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+zoo_runner_common-0.1.1.dist-info/top_level.txt,sha256=TV8APKVcUq2F4UCQo5eW5b_0K3-_uukb7VOl3GF8MzU,29
+zoo_runner_common-0.1.1.dist-info/RECORD,,

zoo_runner_common-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zoo_runner_common-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+base_runner
+zoo_conf
+zoostub

zoostub.py

@@ -0,0 +1,40 @@
+from loguru import logger
+
+
+class ZooStub:
+    def __init__(self):
+        self.SERVICE_ACCEPTED = 0
+        self.SERVICE_STARTED = 1
+        self.SERVICE_PAUSED = 2
+        self.SERVICE_SUCCEEDED = 3
+        self.SERVICE_FAILED = 4
+        self.SERVICE_PAUSED = 5
+        self.SERVICE_DEPLOYED = 6
+        self.SERVICE_UNDEPLOYED = 7
+
+    def update_status(self, conf, progress):
+        print(f"Status {progress}")
+
+    def _(self, message):
+        print(f"invoked _ with {message}")
+
+    def trace(self, message):
+        logger.trace(message)
+
+    def debug(self, message):
+        logger.debug(message)
+
+    def info(self, message):
+        logger.info(message)
+
+    def success(self, message):
+        logger.success(message)
+
+    def warning(self, message):
+        logger.warning(message)
+
+    def error(self, message):
+        logger.error(message)
+
+    def critical(self, message):
+        logger.critical(message)