Setting up OpenSTEF for development#

This guide will help you set up a development environment for OpenSTEF 4.0, which uses a modern Python development stack with uv and a monorepo workspace structure.

Prerequisites#

Python version#

OpenSTEF 4.0 requires Python 3.12 or higher. You can check your Python version with:

python --version

Installing uv#

OpenSTEF 4.0 uses uv as the primary dependency manager and Python project manager. uv is a fast, Rust-based Python package manager that handles both dependency resolution and virtual environments.

Install uv using the recommended method for your platform:

macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pipx

pipx install uv

pip

pip install uv

For more installation options, see the uv installation guide.

Cloning the repository#

Clone the OpenSTEF repository and navigate to the project directory:

git clone https://github.com/OpenSTEF/openstef.git
cd openstef

Setting up the development environment#

OpenSTEF 4.0 uses a workspace structure with multiple packages:

openstef-models: Core forecasting models, feature engineering, and data processing
openstef-beam: Backtesting, evaluation, analysis and metrics
openstef-core: Core utilities, dataset types, shared types and base models used by other packages
docs: Documentation source
openstef-meta: Meta-models for combining and stacking forecasts (ensembles, weighted blends)
openstef-foundation-models: Foundation-model forecasters (e.g. Chronos-2) on an ONNX runtime
openstef-compatibility: Compatibility layer for OpenSTEF 3.x (coming soon)

Install the development dependencies using uv:

uv sync

This installs the default dev dependency group: a curated aggregate of the focused groups (test, lint, typecheck, notebooks, docs, deployment) plus every workspace feature in its CPU flavour. One command gives you the full environment to run the tests, linters, type checker, and docs build — no --all-groups or --all-packages needed.

To install only part of the toolbelt, sync the focused groups directly, e.g. uv sync --no-default-groups --group test for just the test runner.

Note

The default environment installs the CPU compute runtimes (onnxruntime, xgboost-cpu). For a GPU environment, run:

uv sync --no-default-groups --group dev-gpu

The CPU and GPU runtimes are declared as conflicting extras, so do not pass --all-groups or --all-extras — they would try to activate both flavours at once and fail. Install one or the other.

Understanding the workspace structure#

OpenSTEF 4.0 uses a monorepo workspace structure defined in pyproject.toml:

[tool.uv.workspace]
members = [
        "packages/openstef-models",
        "packages/openstef-beam",
        "packages/openstef-core",
  "docs",
]

This means:

All packages are developed together in a single repository
Dependencies between packages are automatically resolved
You can work on multiple packages simultaneously
Changes in one package are immediately available to other packages

Verifying your installation#

Test that your environment is set up correctly:

# Check that uv is working
uv --version

# Check that you can run the task runner
uv run poe --help

# Run a quick test to verify everything works
uv run poe all --check

If everything is working correctly, the last command should run all linting, formatting, type checking, and tests without errors.

Next steps#

Now that you have a working development environment, you can:

Read the Development workflow guide to understand how to contribute
Explore the Documentation Guide guide if you want to contribute to documentation
Look at the good first issues to find something to work on

Development tools overview#

Note that also OpenSTEF 4.0 uses several modern development tools:

uv: Package manager and virtual environment handler (uv website)
Poe the Poet: Task runner for common development tasks (poethepoet website)
Ruff: Lightning-fast linting and formatting (ruff website)
ty: Type checking (ty website)
pytest: Testing framework with coverage reporting (pytest website)
Sphinx: Documentation generation (sphinx website)
REUSE: License compliance checking (reuse website)

All these tools are configured and ready to use through the poe task runner. See poe --help for available commands.

Building documentation#

To build the documentation locally:

# Build the documentation
poe docs

# Build and serve with live reload (recommended for editing)
poe docs --serve

# Clean previous builds
poe docs-clean

The built documentation will be available at docs/build/html/index.html.

Note

Building documentation requires additional dependencies that are included in the development environment. Make sure you’ve run uv sync first.