Metadata-Version: 2.4
Name: openstef
Version: 4.1.1
Summary: Open Short Term Energy forecasting library
Project-URL: Documentation, https://openstef.github.io/openstef/index.html
Project-URL: Homepage, https://lfenergy.org/projects/openstef/
Project-URL: Issues, https://github.com/OpenSTEF/openstef/issues
Project-URL: Repository, https://github.com/OpenSTEF/openstef
Author-email: "Alliander N.V" <openstef@lfenergy.org>
License-Expression: MPL-2.0
License-File: LICENSE.md
Keywords: energy,forecasting,machinelearning
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4.0,>=3.12
Requires-Dist: openstef-core==4.1.1
Requires-Dist: openstef-models[xgb-cpu]==4.1.1
Provides-Extra: all
Requires-Dist: openstef-beam[all]==4.1.1; extra == 'all'
Requires-Dist: openstef-core==4.1.1; extra == 'all'
Requires-Dist: openstef-foundation-models[cpu]==4.1.1; extra == 'all'
Requires-Dist: openstef-meta==4.1.1; extra == 'all'
Requires-Dist: openstef-models[xgb-cpu]==4.1.1; extra == 'all'
Provides-Extra: beam
Requires-Dist: huggingface-hub>=0.35.3; extra == 'beam'
Requires-Dist: openstef-beam==4.1.1; extra == 'beam'
Provides-Extra: core
Requires-Dist: openstef-core==4.1.1; extra == 'core'
Provides-Extra: foundation-models
Requires-Dist: openstef-foundation-models[cpu]==4.1.1; extra == 'foundation-models'
Provides-Extra: meta
Requires-Dist: openstef-meta==4.1.1; extra == 'meta'
Provides-Extra: models
Requires-Dist: openstef-meta==4.1.1; extra == 'models'
Requires-Dist: openstef-models[xgb-cpu]==4.1.1; extra == 'models'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2017-2025 Contributors to the OpenSTEF project <openstef@lfenergy.org>

SPDX-License-Identifier: MPL-2.0
-->

<p align="center">
  <a href="https://www.lfenergy.org/projects/openstef/">
    <img src="https://raw.githubusercontent.com/OpenSTEF/openstef/main/docs/source/logos/openstef-horizontal-color.svg" alt="OpenSTEF Logo" width="400">
  </a>
</p>

# OpenSTEF

[![Downloads](https://static.pepy.tech/badge/openstef)](https://pepy.tech/project/openstef)
[![Downloads](https://static.pepy.tech/badge/openstef/month)](https://pepy.tech/project/openstef)
[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5585/badge)](https://bestpractices.coreinfrastructure.org/projects/5585)
[![License: MPL-2.0](https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg)](LICENSE.md)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
![GitHub Release](https://img.shields.io/github/v/release/openstef/openstef)


[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=alert_status)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)
[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=coverage)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=sqale_rating)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)
[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=reliability_rating)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=security_rating)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)
[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=OpenSTEF_openstef&metric=vulnerabilities)](https://sonarcloud.io/summary/overall?id=OpenSTEF_openstef)


## What is OpenSTEF

**OpenSTEF** (Open Short-Term Energy Forecasting) is an open-source, model-agnostic Python framework for creating short-term forecasts in the energy sector. It provides complete machine learning pipelines for data preprocessing, feature engineering, model training, probabilistic forecasting, and evaluation. Version 4.0.0 introduces a complete architectural refactor with enhanced modularity, full type safety, and modern Python development practices.

For more information, visit the [OpenSTEF project page at LF Energy](https://www.lfenergy.org/projects/openstef/).

## Monorepo Overview

OpenSTEF 4.0.0 is organized as a monorepo with specialized packages under the `packages/` directory:

| Package | Purpose |
|---------|---------|
| **openstef** | Meta-package installing all core components |
| **openstef-core** | Core utilities, dataset types, shared types and base models |
| **openstef-models** | ML models, feature engineering, data processing |
| **openstef-beam** | Backtesting, Evaluation, Analysis, and Metrics |
| **openstef-meta** | Meta models for OpenSTEF |

## How to Install

**Requirements:** Python ≥3.12, 64-bit OS (Windows, macOS, Linux)

```bash
# Minimal-but-runnable convenience layer (core + models with CPU XGBoost)
pip install openstef

# Everything, CPU flavour
pip install "openstef[all]"

# Or install individual packages
pip install openstef-models
pip install openstef-beam
pip install openstef-core

# Optional feature extras (additive)
pip install "openstef-models[lgbm]"
pip install "openstef-models[tuning]"
pip install "openstef-beam[all]"
```

**Compute runtimes (pick one per package).** Packages with a heavy runtime ship
mutually exclusive CPU and GPU builds as conflicting extras — install one, not both:

```bash
# Foundation models (Chronos-2): CPU everywhere, GPU on CUDA Linux/Windows
pip install "openstef-foundation-models[cpu]"
pip install "openstef-foundation-models[gpu]"

# XGBoost models: CPU or GPU
pip install "openstef-models[xgb-cpu]"
pip install "openstef-models[xgb-gpu]"
```

The `openstef` meta-package always ships the CPU builds; for GPU, install the
component package directly with its `[gpu]` extra.

Using [uv](https://docs.astral.sh/uv/) (recommended for development):

```bash
uv add openstef
```

For the complete installation guide including troubleshooting, see the [Installation Documentation](https://openstef.github.io/openstef/user_guide/getting_started/installation.html).

## Examples

Tutorials and usage examples are available in the [`examples/`](examples/) folder. See the examples folder's own `README.md` for an overview of available examples including:

- Forecasting quickstart
- Feature engineering

Additional tutorials are available in the [online documentation](https://openstef.github.io/openstef/examples.html).

## License

**Mozilla Public License Version 2.0** - see [LICENSE.md](LICENSE.md) for details.

This project includes third-party libraries licensed under their respective Open-Source licenses. SPDX-License-Identifier headers show applicable licenses. License files are in the [LICENSES/](LICENSES/) directory.
## Contributing

We welcome contributions to OpenSTEF 4.0! 

**[Read our Contributing Guide](https://openstef.github.io/openstef/contribute/)** - documentation for contributors including:

- How to report bugs and suggest features
- Documentation improvements and examples
- Code contributions and development setup
- Sharing datasets and real-world use cases

### Quick Development Setup

```bash
# Clone and set up for development (one command installs the full CPU dev env)
git clone https://github.com/OpenSTEF/openstef.git
cd openstef
uv sync

# Run tests and quality checks
uv run poe all
```

> GPU dev env (CUDA; Linux/Windows): `uv sync --no-default-groups --group dev-gpu`.
> Do not use `--all-groups`/`--all-extras` — the CPU and GPU runtimes conflict.

**Code of Conduct**: We follow the [Contributor Code of Conduct](https://openstef.github.io/openstef/contribute/code_of_conduct.html) to ensure a welcoming environment for all contributors.
## Citations

If you use OpenSTEF in your research or publications, please cite the project. Refer to the [CITATION.cff](CITATION.cff) file in this repository for the preferred citation format, or use:

> Contributors to the OpenSTEF project. *OpenSTEF — Open Short-Term Energy Forecasting*. LF Energy, 2017–2025. Available at: https://github.com/OpenSTEF/openstef

## Contact

- **Slack:** [LF Energy Slack](https://slack.lfenergy.org/)
- **Email:** openstef@lfenergy.org
- **Community meeting:** [OpenSTEF four-weekly community meeting](https://lf-energy.atlassian.net/wiki/spaces/OS/pages/32278358/OpenSTEF+four-weekly+community+meeting)
- **Issues:** [GitHub Issue Tracker](https://github.com/OpenSTEF/openstef/issues)
- **Support Guide:** [How to get help](https://openstef.github.io/openstef/project/support.html)
