kuristo 0.11.0

A simple automation framework

Kuristo

Kuristo is a flexible, plugin-enabled automation framework designed for scientific and HPC workflows. It supports sequential and parallel job execution, workflow definition via YAML, resource-aware scheduling, custom step and action definitions, and rich output with optional headless mode.

Features

• YAML-based workflows (GitHub Actions style)
• Custom steps and actions via Python plugins
• Job dependency graph with parallel execution
• Job labels for selective execution
• Resource-aware scheduling with core-aware limits
• Step & job timeouts
• ANSI-rich output or plain mode for CI
• Environment variable passing and output capture
• Output validation (regex, float comparisons, CSV diffing)
• Composite steps for reusable action pipelines
• Built-in log directory and run tracking
• Run tagging system to protect important results from cleanup
• Test coverage with pytest
• MPI support via configurable launcher (mpirun, mpiexec, etc.)

Install

Install from PyPI:

pip install kuristo

Or clone the repo and install locally:

git clone https://github.com/andrsd/kuristo.git
cd kuristo
pip install -e .

Usage

Run all tests in a directory:

kuristo run tests/assets/

Run a specific test set:

kuristo run tests/assets/tests1

Check your environment:

kuristo doctor

Headless/CI-safe mode

kuristo run tests --no-ansi

Workflow YAML Example

jobs:
  test-matrix:
    labels: [simulation, slow]
    strategy:
      matrix:
        include:
          - os: ubuntu
            version: 20.04
          - os: ubuntu
            version: 22.04

    steps:
      - name: Run simulation
        id: simulation
        run: ./simulate --config=${{ matrix.version }}

      - name: Check output
        uses: checks/regex
        with:
          input: ${{ steps.simulation.output }}
          pattern: "SUCCESS"

Writing Custom Actions

Create a plugin in .kuristo/actions.py:

import kuristo

@kuristo.action("my/special-step")
class MyAction(kuristo.ProcessAction):
    def __init__(self, name, context: kuristo.Context, **kwargs):
        super().__init__(name, context, **kwargs)
        self.input = kwargs["input"]

    def create_command(self):
        return f"echo Hello {self.input}"

Then, use in the workflow as:

jobs:
  test:
    steps:
      - name: My special test
        uses: my/special-step
        with:
          input: "world"

Kuristo will auto-discover .py files in .kuristo/.

Logging & Output

All logs and run data are saved in:

.kuristo-out/
├── runs/
│   ├── latest → 20250620_101500/
│   └── 20250620_101500/

Set logging retention and cleanup in config.yaml:

log:
  dir-name: .kuristo-out
  history: 5
  cleanup: on_success

Configuration

You can define a global config at .kuristo/config.yaml:

resources:
  num-cores: 8

runner:
  mpi-launcher: mpiexec

Or override via environment variable:

KURISTO_MPI_LAUNCHER=mpiexec2 kuristo run tests/

Testing & Coverage

Run tests:

pytest -v

With coverage:

pytest --cov=kuristo --cov-report=term-missing

Philosophy

Kuristo is inspired by the structure of GitHub Actions but tailored for local and HPC workflows. It aims to be lightweight, extensible, and scriptable — with strong support for reproducibility and numerical simulation validation.

License

MIT

Fun Fact

"Kuristo" means "runner" in Esperanto. Because that’s what it does — it runs your stuff.