Packaging API

Public API for packaging a trained model for distribution.

Packaging is the last step of the documented workflow, so it belongs on the supported surface rather than behind pstrain.lib.steps.package.

pstrain.api.packaging.create_noisedict(output_path, filler_dict_path=None)[source]

Create noisedict file for Sphinx decoders.

This is the filler dictionary used during decoding.

Parameters:

  • output_path (Path) – Output file path

  • filler_dict_path (Path | None) – Source filler dictionary (optional)

Returns:

Path to created file

Return type:

Path

pstrain.api.packaging.package_model(model_dir, output_dir, model_name=None, dictionary_path=None, filler_dict_path=None, include_dict=True, *, overwrite=False)[source]

Package a trained model for distribution.

Creates a complete, self-contained model directory that can be used directly with PocketSphinx and other Sphinx decoders.

Parameters:

  • model_dir (Path) – Source model directory

  • output_dir (Path) – Output directory for packaged model

  • model_name (str | None) – Name for the model (used in output path)

  • dictionary_path (Path | None) – Path to pronunciation dictionary

  • filler_dict_path (Path | None) – Path to filler dictionary

  • include_dict (bool) – Whether to include dictionary in package

  • overwrite (bool) – Allow replacement of a recognizable package without a marker

Returns:

Dict mapping file types to output paths

Return type:

dict[str, Path]

Notes

A supported package marker permits replacement by default; a recognizable legacy package without a marker requires overwrite=True. Unrecognized destinations and invalid or unsupported markers are never replaced.

On macOS and Linux, replacement opens the source, destination parent, staging directory, retained package, and recovery directory without following their final names. Identities come from those descriptors; validation and traversal remain descriptor-relative; and every rename is reconciled from the filesystem even when its call raises. Windows retains the path-based transaction and makes no guarantee against an active process substituting names during packaging. An asynchronous interruption can also leave a mixed unnamed package on Windows because its path transaction cannot reconcile a rename that completed before raising. No supported platform promises safety against every active same-filesystem race because final directory-entry deletion has no portable conditional-by-descriptor primitive. See docs/package-safety.md for the exact guarantee, recovery instructions, and remaining seams.

With no model name, acoustic, dict, README.txt, and pstrain-package.json transition separately. On a handled failure the implementation reconciles each open identity and attempts to restore the previous public set. Individual paths can be absent during that recovery; failures are attached to the initiating exception and recovery directories are retained when certainty is lost. Unrelated entries in output_dir are preserved.

Example output structure:

dist/models/my-model/
├── acoustic/
│   ├── feat.params
│   ├── mdef
│   ├── means
│   ├── variances
│   ├── mixture_weights
│   ├── transition_matrices
│   └── noisedict
├── dict/
│   ├── cmudict.dict
│   └── filler.dict
└── README.txt
pstrain.api.packaging.validate_package_destination(model_dir, output_dir, model_name=None, *, include_dict=True, overwrite=False)[source]

Validate a package destination without changing the filesystem.

Named packages replace their complete destination. Unnamed packages replace only their generated entries and preserve unrelated entries in output_dir. Existing generated entries must belong to a recognizable package in either case. A supported package marker establishes ownership; replacing a legacy package without one requires explicit opt-in.

Parameters:

  • model_dir (Path) – Source model directory

  • output_dir (Path) – Output directory for packaged model

  • model_name (str | None) – Name for the model, as one ordinary path component

  • include_dict (bool) – Whether packaging will replace the generated dictionary directory

  • overwrite (bool) – Allow replacement of a recognizable package without a marker

Returns:

The package directory that packaging will write

Raises:

ValueError – If the name, source relationship, or existing destination is unsafe

Return type:

Path