Diagnostics API

Public API for environment diagnostics.

pstrain.api.diagnostics.fp_contract_policy()

Return the floating-point contraction policy declared by the native build.

Return type:

str

pstrain.api.diagnostics.learning_curves(project_dir, config='default')

Return Baum-Welch pass records for the project’s trained stages.

config is the model config-directory name below each stage in shared/models, not a request to resolve a profile. Stages without a telemetry file are skipped, so a project with no trained models returns an empty list. A telemetry file that exists but is unreadable or invalid raises the same contextual error as load_bw_telemetry().

Results are in canonical acoustic-ladder order from the pipeline’s target declarations. This is not a record of historical execution order: stale or independently trained stages retain their canonical position. Recovering actual execution order would require run or stage order to be recorded in project provenance. Filesystem modification times are deliberately ignored.

Parameters:

• project_dir (Path)

• config (str)

Return type:

list[tuple[str, list[dict[str, Any]]]]

pstrain.api.diagnostics.load_bw_telemetry(model_dir)

Load a Baum-Welch telemetry document from model_dir.

Supported schema versions 1 and 2 contain the same core passes fields used here. Each pass reports its number, total and per-frame likelihoods, frame count, signed convergence delta, and stop decision; performance, accounting, and shard details are optional. The returned dictionary is newly decoded on every call.

Raises:

• FileNotFoundError – If model_dir/bw_telemetry.json does not exist.

• ValueError – If the file cannot be decoded, uses an unsupported schema, or lacks the required pass fields.

Parameters:

model_dir (Path)

Return type:

dict[str, Any]

pstrain.api.diagnostics.native_library_available()

Return whether the native pstrain library can be loaded.

Return type:

bool

pstrain.api.diagnostics.resolve_binary(name, bin_dir=None)

Resolve a program exactly as CommandBuilder will execute it.

Parameters:

• name (str)

• bin_dir (Path | None)

Return type:

Path | None

pstrain.api.diagnostics.PSTRAIN_BINARIES

Names of the native pstrain command-line programs.