Metadata-Version: 2.4
Name: fasthep-carpenter
Version: 2026.6.1
Summary: HEP analysis components for FAST-HEP workflows.
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: awkward
Requires-Dist: fasthep-flow>=2026.5.0
Requires-Dist: hist
Requires-Dist: numpy
Requires-Dist: uproot
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# fasthep-carpenter

[![CI](https://github.com/FAST-HEP/fasthep-carpenter/actions/workflows/ci.yml/badge.svg)](https://github.com/FAST-HEP/fasthep-carpenter/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fasthep-carpenter)](https://pypi.org/project/fasthep-carpenter/)
[![Python Versions](https://img.shields.io/pypi/pyversions/fasthep-carpenter)](https://pypi.org/project/fasthep-carpenter/)
[![Documentation Status](https://readthedocs.org/projects/fasthep-carpenter/badge/?version=latest)](https://fasthep-carpenter.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-carpenter` provides common analysis building blocks for FAST-HEP workflows.

It contains reusable High Energy Physics transforms, sources, sinks, and runtime helpers built on top of `fasthep-flow`.

The Python import namespace is:

```python
import fasthep_carpenter
```

## Scope

`fasthep-carpenter` is responsible for:

* ROOT and awkward-array based sources
* event stream manipulation
* HEP analysis transforms
* histogram filling
* cutflows
* object selection helpers
* common CMS/LHC analysis utilities
* workflow runtime extensions

It is the main “analysis implementation” layer of the FAST-HEP ecosystem.

## Relationship to `fasthep-flow`

`fasthep-flow` provides:

* workflow compilation
* execution planning
* orchestration
* registries
* backend interfaces

`fasthep-carpenter` provides:

* concrete analysis operations
* HEP-specific runtime behaviour
* physics object manipulation
* common workflow primitives

In practice, most HEP users will use both packages together.

## Recommended companion packages

* `fasthep-flow`

  * workflow language and execution engine

* `fasthep-curator`

  * dataset inspection
  * schema generation
  * metadata snapshots

* `fasthep-render`

  * plotting
  * tables
  * reports

* `fasthep-cli`

  * the `fasthep` command-line interface

Alternatively, install the meta package:

```bash
pip install fasthep
```

## Installation

Install directly:

```bash
pip install fasthep-carpenter
```

Development environment:

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

## Minimal example

Example transform registration:

```yaml
registry:
  transforms:
    define:
      spec: fasthep_carpenter.spec.define_transform:DEFINE_TRANSFORM_SPEC
      impl: fasthep_carpenter.impl.define_transform:run_define_transform
```

Example workflow snippet:

```yaml
steps:
  - id: TightMuon
    op: hep.select
    params:
      collection: Muon
      mask: Muon_tightId
```

## Design principles

`fasthep-carpenter` focuses on:

* reusable analysis primitives
* declarative workflows
* registry-driven extension
* experiment-agnostic interfaces where possible
* compatibility with awkward-array based analysis ecosystems

The package intentionally separates workflow orchestration (`fasthep-flow`) from domain-specific analysis behaviour.

## Documentation

Main FAST-HEP documentation:

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

API documentation for this package:

* [https://fasthep-carpenter.readthedocs.io/en/latest/](https://fasthep-carpenter.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.
