Metadata-Version: 2.5
Name: sdflow
Version: 0.1.0
Summary: Open-source framework for sequential decision problems: problems built from point-in-time data, environments and objectives; predictors, optimizers, simulators and agents; one engine for backtest, simulation and live
Project-URL: Homepage, https://github.com/rebase-energy/sdflow
Project-URL: Repository, https://github.com/rebase-energy/sdflow
Author: rebase.energy
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: fsspec>=2023.1.0
Requires-Dist: gymnasium>=1.1.1
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=15.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: build-data
Requires-Dist: netcdf4>=1.6; extra == 'build-data'
Requires-Dist: xarray>=2024.1; extra == 'build-data'
Provides-Extra: energy
Requires-Dist: energydatamodel<0.8.0,>=0.7.0; extra == 'energy'
Provides-Extra: examples
Requires-Dist: matplotlib>=3.8; extra == 'examples'
Requires-Dist: plotly>=5.0; extra == 'examples'
Description-Content-Type: text/markdown

<div align="center">
<h1>sdflow</h1>
<p><b>Open-source Python framework for sequential decision problems.</b></p>
</div>

A sequential decision problem is a loop. State **S_t** is observed, a decision
**a_t = A^π(S_t)** is taken, exogenous information **W_{t+1}** is revealed, a new state
**S_{t+1} = S^M(S_t, a_t, W_{t+1})** is reached and a contribution **C(S_t, a_t, W_{t+1})**
is earned. The goal is a policy **π** that maximises the expected total contribution.

sdflow gives that loop a concrete form:

- **Problems** built from point-in-time **datasets**, **environments** and **objectives**:
  every field is bitemporal, so a model physically cannot read data that was not knowable
  at the decision origin.
- **Policies** built from **predictors**, **optimizers** and **simulators**, connected by
  **agents**.
- **One engine** that runs a policy the same way in a backtest over history, a simulation
  over synthetic exogenous information, and live operation.
- **Verifiable scoring**: official splits, a `Verifier` that fits a fresh submission itself
  and scores the hidden holdout, bundled benchmarks with reference baselines.

The core is domain-neutral. Energy, the best-supported domain, is an extra:
`sdflow[energy]` adds the asset classes built on
[energydatamodel](https://github.com/rebase-energy/energydatamodel). sdflow is the
successor of [emflow](https://github.com/rebase-energy/emflow); emflow 0.3 code ports by
renaming the import.

## Installation

```bash
pip install sdflow            # the core
pip install "sdflow[energy]"  # plus the energy asset classes
```

## Quick start

```python
import sdflow as sd

problem = sd.load_problem("gefcom2014:solar")      # a bundled benchmark
result = sd.evaluate(problem, sd.Predictor.persistence(), split="validation")
print(result.score, result.n_origins)
```

A predictor is `fit(train)` on a leakage-safe training view and `predict(obs)` per decision
origin; the environment computes the objective from what it returns. See `docs/` for the
walkthrough: datasets and feeds, environments, features, models, problems and the run engine.

## Registering your own problems

Problems in other packages register through the `sdflow.problems` entry-point group and
then load by name anywhere the package is installed:

```toml
[project.entry-points."sdflow.problems"]
icing = "my_signals.icing.problem"
```

```python
sd.load_problem("icing:se1")
```

Data can live on the Hugging Face Hub: a dataset repo with a `rebase.yaml` marker is
readable through the `rb://` filesystem sdflow registers with fsspec
(`pd.read_parquet("rb://dataset/<owner>/<repo>/<path>")`).

## Development

```bash
uv sync --group dev
uv run pytest
```

MIT licensed. Built by [rebase.energy](https://www.rebase.energy).
