fasthep-curator

fasthep-curator provides dataset inspection, metadata extraction, validation, and schema generation utilities for FAST-HEP workflows.

The Python import namespace is:

import fasthep_curator

Scope

fasthep-curator is responsible for:

• dataset inspection
• branch discovery
• schema generation
• metadata extraction
• validation helpers
• workflow diagnostics
• runtime error reporting helpers
• caching of inspection artifacts

It is the dataset and metadata management layer of the FAST-HEP ecosystem.

Relationship to fasthep-flow

fasthep-flow provides:

• workflow compilation
• orchestration
• execution planning
• backend interfaces

fasthep-curator provides:

• dataset metadata
• source schemas
• validation utilities
• dataset inspection tooling
• diagnostics and reporting helpers

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

Recommended companion packages

• fasthep-flow

  • workflow language and execution engine

• fasthep-carpenter

  • HEP analysis transforms
  • histogramming
  • event processing

• fasthep-render

  • plotting
  • tables
  • reports

• fasthep-cli

  • the unified fasthep command-line interface

Alternatively, install the meta package:

pip install fasthep

Installation

Install directly:

pip install fasthep-curator

Development environment:

pixi install
pixi run ci

Minimal example

Example dataset inspection:

datasets:
  DYJets:
    files:
      - /data/example.root
    source:
      type: root_tree
      tree: Events

Example metadata artifact:

source_schema:
  events:
    pt: float
    eta: float
    phi: float

ROOT Schema Inspection

Curator provides the reusable Python schema-inspection API. Command-line access is exposed through the central FAST-HEP CLI.

Inspect a ROOT TTree interactively:

fasthep inspect schema input.root --tree Events

The default output is a readable table with field name, logical dtype, shape, and ROOT storage type.

Extract a pasteable YAML list for keep: or drop: workflow parameters:

fasthep inspect schema input.root \
  --tree Events \
  --include 'GenJet*' \
  --include 'GenMET*' \
  --include 'Generator_*' \
  --format yaml-list

Generate a starter hep.align_schema document:

fasthep inspect schema input.root \
  --tree Events \
  --include 'GenJetAK8_*' \
  --format alignment

Field filters use shell-style glob matching. Repeated --include options are unioned in source field order; repeated --exclude options remove matches after includes:

fasthep inspect schema input.root \
  --tree Events \
  --include 'Gen*' \
  --exclude 'GenPart_*'

The same inspection implementation is available from Python:

from fasthep_curator.api import inspect_root_tree_schema

schema = inspect_root_tree_schema("input.root", tree="Events")

Design principles

fasthep-curator focuses on:

• reproducible metadata
• reusable inspection artifacts
• declarative validation
• cached schema discovery
• workflow diagnostics
• experiment-agnostic interfaces where possible

The package intentionally separates dataset/metadata management from workflow orchestration and analysis execution.

Documentation

Main FAST-HEP documentation:

• https://fast-hep.github.io

API documentation for this package:

• https://fasthep-curator.readthedocs.io/en/latest/

Repository

Main FAST-HEP repository and project links:

• 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

Earlier prototype implementations are preserved in legacy repositories and branches.

The current repository contains the split-package FAST-HEP architecture.

Status

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

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