Control-flow and error-handling Actions for IOMate.

iomate-pkg-workflow is an IOMate Package built on top of iomate-base.

It provides Actions for controlling execution flow and handling errors inside IOMate Automations.

---

Features

The Package provides two main Action Groups:

Workflow
├── workflow.if
├── workflow.else_if
└── workflow.else

Error Handling
├── error_handling.try
├── error_handling.except
└── error_handling.finally

These Actions are designed to integrate with the IOMate runtime and follow the Action, Variable, and Contract abstractions provided by iomate-pkg-workflow.

---

Requirements

• Python 3.12+
• Poetry
• iomate-base

The supported Python version range is defined in pyproject.toml.

---

Installation

Install from PyPI:

pip install iomate-pkg-workflow

Or add it to a Poetry project:

poetry add iomate-pkg-workflow

The Package requires a compatible version of:

iomate-base

---

Development Setup

Clone the repository and install the development dependencies:

poetry install

Run commands through Poetry:

poetry run <command>

---

Project Structure

iomate-pkg-workflow/
├── pyproject.toml
├── poetry.lock
│
├── src/
│   └── iomate_pkg_workflow/
│       ├── actions/
│       │   ├── workflow/
│       │   └── error_handling/
│       ├── package.py
│       └── ...
│
├── tests/
│   ├── workflow/
│   ├── error_handling/
│   └── ...
│
├── README.md
├── CONTRIBUTING.md
└── CODE_OF_CONDUCT.md

The exact internal structure may evolve as the Package grows, but Package-specific implementation must remain isolated from iomate-base.

---

Action Groups

Workflow

The Workflow group provides conditional control-flow Actions.

workflow.if
workflow.else_if
workflow.else

These Actions allow an Automation to select execution paths based on conditions evaluated during runtime.

Conceptually:

workflow.if
    │
    ├── condition = true
    │       ↓
    │    execute branch
    │
    └── condition = false
            ↓
       evaluate else_if / else

---

Error Handling

The Error Handling group provides Actions for defining error-handling execution scopes.

error_handling.try
error_handling.except
error_handling.finally

Conceptually:

try
 │
 ├── Action
 ├── Action
 └── Action
      │
      ├── success → continue
      │
      └── error → except
                    │
                    └── finally

The actual execution semantics are defined by the IOMate runtime and the Action Contracts exposed by this Package.

---

Action Contracts

Each Action has a stable key and a versioned contract.

Examples:

workflow.if
workflow.else_if
workflow.else
error_handling.try
error_handling.except
error_handling.finally

Action Contracts define the interface consumed by the IOMate runtime, including:

• Inputs
• Outputs
• Type constraints
• Variable flags
• Contract version
• Execution metadata

Example:

{
  "key": "workflow.if",
  "version": "1.0.0",
  "inputs": [
    {
      "name": "condition",
      "type": "boolean",
      "required": true
    }
  ],
  "outputs": []
}

Contract changes must preserve backward compatibility whenever possible.

Breaking changes require an appropriate contract version change.

---

iomate-pkg-workflow

This Package depends on iomate-base for the core IOMate abstractions.

The dependency direction must remain:

iomate-base
     ↑
     │
iomate-pkg-workflow

iomate-pkg-workflow must not implement its own versions of:

• Variables
• Type Definitions
• Actions
• Action Contracts
• Package Registry
• Runtime abstractions

These capabilities must come from iomate-base.

---

Package Interoperability

The Package must remain independent of other IOMate Packages.

For example, iomate-pkg-workflow must not directly depend on:

iomate-pkg-selenium
iomate-pkg-http
iomate-pkg-claude

Interoperability between Packages is achieved through the shared IOMate runtime and Variables defined by iomate-base.

iomate-base
        │
        │ Variables
        ▼
    IOMate Runtime
        ▲
        │
        │ Variables
        │
iomate-pkg-workflow

This keeps Packages independently installable and reusable.

---

Testing

Run the complete test suite:

poetry run pytest

Run tests with coverage:

poetry run pytest --cov=src/iomate_pkg_workflow --cov-report=term

The project requires a minimum coverage of:

80%

Tests should cover:

• Action registration
• Action discovery
• Action metadata
• Input validation
• Output definitions
• Action Contracts
• Conditional behavior
• Error-handling behavior
• Contract compatibility

---

Code Quality

Run Ruff:

poetry run ruff check .

Check formatting:

poetry run ruff format --check .

Format the project:

poetry run ruff format .

Run MyPy:

poetry run mypy src

---

Pre-commit

Install the project's pre-commit hooks:

poetry run pre-commit install

Run all hooks:

poetry run pre-commit run --all-files

Run tests and type checking separately:

poetry run pytest
poetry run mypy src

---

Documentation

Documentation should be updated when changes affect:

• Action behavior
• Action Contracts
• Inputs
• Outputs
• Type constraints
• Error handling
• Control-flow semantics
• Package configuration
• Compatibility requirements

Public Actions should include clear documentation and type annotations.

---

Versioning

iomate-pkg-workflow follows Semantic Versioning:

MAJOR.MINOR.PATCH

Examples:

1.0.0
1.1.0
1.1.1

MAJOR

Breaking changes to public Package behavior or Action Contracts.

MINOR

Backward-compatible functionality, such as:

• New Actions
• New optional inputs
• New Action Groups

PATCH

Backward-compatible fixes, such as:

• Bug fixes
• Internal implementation corrections
• Documentation corrections

---

Contributing

See CONTRIBUTING.md for:

• Branching strategy
• Development workflow
• Pull Request requirements
• Testing requirements
• Commit conventions
• Release process

See CODE_OF_CONDUCT.md for the project's community standards.

---

Release Process

Releases are prepared from staging.

The general release flow is:

feature branch
      ↓
Pull Request
      ↓
staging
      ↓
release preparation
      ↓
release
      ↓
version/tag
      ↓
PyPI

Before publishing a release:

• All CI checks must pass
• Version must be updated according to Semantic Versioning
• Action Contract compatibility must be reviewed
• Package dependencies must be validated
• Release notes should be prepared
• Package artifacts must be validated
• The final version must be tagged in Git

The release artifact is published to PyPI as:

iomate-pkg-workflow

---

License

See LICENSE for licensing information.

---

Architecture

iomate-pkg-workflow provides control-flow capabilities to the IOMate execution system while relying on iomate-pkg-workflow for its core contracts.

                    IOMate Runtime
                          │
                          │
                    iomate-pkg-workflow
                          │
                          ▼
              iomate-pkg-workflow
                    │           │
                    │           │
              Workflow      Error Handling
                    │           │
              ┌─────┴─────┐ ┌───┴─────────┐
              │     │     │ │      │      │
             if  else_if else try  except finally

The core principles are:

iomate-pkg-workflow → Core Contracts
Package     → Workflow Capabilities
Actions     → Executable Behavior
Variables   → Interoperability
Contracts   → Compatibility