Contributor Extension Guide

This guide is the entry point for contributors extending the maintained hyperion package. It describes where a change belongs and which existing contracts it must preserve. It deliberately does not treat egs/ recipes or hyperion/bin_deprec* as extension templates: those trees are outside the supported product surface.

Choose the extension point

Start with the smallest maintained component that owns the new behavior.

Maintained extension points

You are adding

Put it under

Start with

A serializable NumPy model, transform, PDF, calibrator, or score method

hyperion.np

Model Extension Contracts and NumPy Backend Extension Points

A primitive PyTorch operation

hyperion.torch.layers

PyTorch Extension Workflows

A reusable composition of layers

hyperion.torch.layer_blocks

PyTorch Extension Workflows

A reusable neural architecture

hyperion.torch.narchs

NetArch and PyTorch Extension Workflows

A task model, model checkpoint, or model-specific inference behavior

hyperion.torch.models

Model Extension Contracts and PyTorch API Contracts

Batching, sampling, training, logging, or optimization behavior

hyperion.torch.data or hyperion.torch.trainers

PyTorch Extension Workflows and PyTorch Training Support

Dataset-specific manifest preparation

hyperion.data_prep

Data-Preparation and CLI Extension Workflows

A maintained command

hyperion.bin

Data-Preparation and CLI Extension Workflows

Architectural boundaries

The PyTorch stack has a deliberate dependency direction:

layers → layer_blocks → narchs → models → trainers.

Keep reusable computation below the model layer. A model owns task-specific forward/loss/embedding behavior; a trainer owns optimization, checkpointing, distributed execution, AMP, and logging. New dataset or sampler behavior must preserve the selected trainer’s batch contract. See Repository Architecture for the package layout and PyTorch Extension Points for the current public contracts.

For NumPy components, keep embedding transforms, PLDA/PDFs, score normalization, calibration, and evaluation as independently serializable artifacts. Do not couple a score-side component to a PyTorch checkpoint unless the public model contract explicitly requires it.

Contributor responsibilities

Before making a public extension, identify these decisions:

  • Public contract: constructor arguments, types, shapes, outputs, errors, and side effects.

  • Configuration and serialization: whether the component participates in a registry, needs get_config(), and must load artifacts produced by earlier releases.

  • Configuration-facing integration: whether a factory or jsonargparse class-argument interface is preferable to custom CLI plumbing.

  • Support level: stable additions require compatibility and migration planning; experimental additions must be labelled as such. See Documentation Policy.

  • Validation: select targeted tests, update a public CLI inventory entry if applicable, regenerate derived CLI docs, and run the checks in Building the Documentation.

The Phase 6 workflow pages expand these conventions with maintained code patterns. Use the nearest maintained component in the target subsystem as the implementation pattern, not a similarly named legacy script.

See also