Metadata-Version: 2.4
Name: exa-atow-runtime
Version: 0.1.0
Summary: Runtime support for executing HAPS applications
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ebsclient
Dynamic: license-file

# Exa-AToW Runtime

Runtime support for proxies generated by the Exa-AToW Workflow Compiler.

## Overview

The Exa-AToW Runtime provides the shared execution logic used by generated Galaxy tools, CWL tasks, and MCP servers to invoke HAPS applications.

The runtime is separated from the compiler because they are used at different stages:

- `exa-atow-compiler` generates executable workflow and tool descriptions.
- `exa-atow-runtime` supports the generated proxies while they are running.

This separation allows execution environments, such as Galaxy servers, to install the lightweight runtime without installing all compiler dependencies.

## Features

The runtime supports:

- Submission of HAPS jobs through `ebsclient`
- Monitoring of submitted jobs
- Recovery of previously submitted jobs
- Persistent job-state management
- Processing of HAPS results
- Downloading eBout outputs
- Generation of JSON metadata for downstream workflow tasks

## Installation

The recommended installation method is to install the complete Exa-AToW compiler:

```bash
python -m pip install exa-atow-compiler
```

A compatible version of `exa-atow-runtime` is installed automatically.

Execution environments that only run generated proxies can install the runtime directly:

```bash
python -m pip install exa-atow-runtime
```

## Requirements

- Python 3.11 or newer
- Access to a configured HAPS service
- Credentials and HPC-centre information required by the generated proxy

The runtime installs `ebsclient` as a dependency.

## Usage

The runtime is normally not invoked directly from the command line. It is imported by the Python proxies generated by the Exa-AToW compiler.

For example, generated proxies import runtime functionality using:

```python
from exa_atow_runtime import run_haps
```

Depending on the compilation mode, generated code may also use runtime functions for recovery, metadata generation, output downloading, and job-state management.

## Compilation and execution model

The compiler and runtime participate in different stages of an Exa-AToW workflow:

1. The Exa-AToW compiler reads XGTD HAPS descriptions.
2. It generates Galaxy tools, CWL tasks, or MCP servers.
3. The generated proxy is executed by the target workflow environment.
4. The proxy uses `exa-atow-runtime` to submit and monitor the HAPS job.
5. The runtime processes the results and produces metadata for subsequent tasks.

## Version compatibility

The Exa-AToW compiler declares the compatible runtime versions in its package dependencies. Users installing the compiler therefore receive a compatible runtime automatically.

For example:

```toml
dependencies = [
    "exa-atow-runtime>=0.1.0,<0.2.0",
]
```

## Development installation

From the `runtime` directory, install the package in editable mode:

```bash
python -m pip install -e .
```

To build the runtime distribution:

```bash
python -m pip install --upgrade build
python -m build
```

The resulting wheel and source distribution are created under `dist/`.
