Metadata-Version: 2.4
Name: fasthep-flow
Version: 2026.6.1
Summary: Dependency-light FAST-HEP graph workflow core.
Author: FAST-HEP contributors
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pyyaml
Provides-Extra: dask-local
Requires-Dist: dask[complete]; extra == 'dask-local'
Provides-Extra: docs
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: pydata-sphinx-theme; extra == 'docs'
Requires-Dist: sphinx; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
Provides-Extra: local
Requires-Dist: awkward; extra == 'local'
Requires-Dist: uproot; extra == 'local'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# fasthep-flow

[![CI](https://github.com/FAST-HEP/fasthep-flow/actions/workflows/ci.yml/badge.svg)](https://github.com/FAST-HEP/fasthep-flow/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fasthep-flow)](https://pypi.org/project/fasthep-flow/)
[![Python Versions](https://img.shields.io/pypi/pyversions/fasthep-flow)](https://pypi.org/project/fasthep-flow/)
[![Documentation Status](https://readthedocs.org/projects/fasthep-flow/badge/?version=latest)](https://fasthep-flow.readthedocs.io/en/latest/)
[![Discussions](https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github)](https://github.com/FAST-HEP/fasthep/discussions)

<p align="center">
  <a href="https://github.com/FAST-HEP/fasthep">
    <picture>
      <source
        media="(prefers-color-scheme: dark)"
        srcset="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-white.png"
      >
      <source
        media="(prefers-color-scheme: light)"
        srcset="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-black.png"
      >
      <img
        alt="FAST-HEP"
        src="https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-black.png"
        width="500"
      >
    </picture>
  </a>
</p>

`fasthep-flow` provides the core FAST-HEP workflow language and execution engine.

It is responsible for:

* workflow compilation
* execution planning
* runtime orchestration
* registry/profile loading
* backend interfaces
* artifact lifecycle management

The Python import namespace is:

```python
import hepflow
```

## Scope

`fasthep-flow` is intentionally lightweight and domain-agnostic.

It does **not** implement:

* ROOT IO
* histogram filling
* HEP-specific transforms
* plotting/rendering
* experiment-specific analysis logic

Those capabilities are provided by companion FAST-HEP packages.

## Recommended companion packages

For High Energy Physics (HEP) workflows, most users will also want:

* `fasthep-carpenter`

  * HEP analysis transforms
  * ROOT/awkward sources and writers
  * histogramming
  * cutflows
  * object reconstruction helpers

* `fasthep-curator`

  * dataset inspection
  * schema snapshots
  * diagnostics
  * runtime hooks

* `fasthep-render`

  * plotting
  * tables
  * reports
  * render styles

* `fasthep-cli`

  * the `fasthep` command-line interface

Alternatively, install the meta package:

```bash
pip install fasthep
```

## Installation

Core workflow package only:

```bash
pip install fasthep-flow
```

Development environment:

```bash
pixi install
pixi run ci
```

## Minimal example

```python
from hepflow.api import compile_author_file, run_author_file

compile_author_file(
    "analysis/author.yaml",
    work_dir="build/example",
)

run_author_file(
    "analysis/author.yaml",
    outdir="build/example",
)
```

## Design principles

`fasthep-flow` focuses on:

* small and composable interfaces
* explicit workflow compilation stages
* registry-driven extensibility
* backend-independent execution planning
* reproducible workflow artifacts
* minimal domain assumptions

The long-term goal is to make the workflow layer reusable beyond High Energy Physics.

## Documentation

Main FAST-HEP documentation:

* [https://fast-hep.github.io](https://fast-hep.github.io)

API documentation for this package:

* [https://fasthep-flow.readthedocs.io/en/latest/](https://fasthep-flow.readthedocs.io/en/latest/)

## Repository

Main FAST-HEP repository and project links:

* [https://github.com/FAST-HEP/fasthep](https://github.com/FAST-HEP/fasthep)

## Contributing

Contribution guidelines, development setup, and project-wide documentation are maintained centrally in the main FAST-HEP repository.

## Legacy branch

The pre-split prototype implementation is preserved in the `legacy` branch.

The new `main` branch contains the split-package architecture.

## Status

FAST-HEP is currently in active pre-alpha development.

Interfaces may still evolve rapidly while the package split and stabilization work continues.
