Configuration API

Public API for configuration operations.

pstrain.api.config.generate_markdown_docs()

Generate Markdown documentation for all config parameters.

Returns:

Markdown string suitable for docs

Return type:

str

pstrain.api.config.generate_rst_docs()

Generate reStructuredText documentation for all config parameters.

Returns:

RST string suitable for Sphinx docs

Return type:

str

pstrain.api.config.get_schema()

Get the canonical profile JSON schema.

Returns:

JSON Schema dict (for docs generation, validation, etc.)

Return type:

dict[str, Any]

pstrain.api.config.get_user_config(config_file=None, force_reload=False)

Get user configuration instance with caching.

Parameters:

• config_file (Path | None) – Path to config file (overrides default lookup)

• force_reload (bool) – Force reload from disk (bypass cache)

Returns:

PstrainUserConfig instance

Return type:

PstrainUserConfig

pstrain.api.config.list_parameters(prefix='')

List all configuration parameters with descriptions.

Parameters:

prefix (str) – Optional prefix to filter parameters (e.g., “audio”, “features”)

Returns:

List of ParameterInfo objects

Return type:

list[ParameterInfo]

pstrain.api.config.list_profiles(project_dir)

List profiles through a concrete public-API call frame.

Parameters:

project_dir (Path)

Return type:

list[dict[str, Any]]

pstrain.api.config.migrate_project(project_dir, *, check)

Render or atomically write the canonical profiles document.

Parameters:

• project_dir (Path)

• check (bool)

Return type:

tuple[Path, str, Path | None]

pstrain.api.config.resolve_config(project_dir, *, profile_name='default', experiment='default', cli_overrides=None, user_config_path=None)

Resolve built-in < user < project < experiment < CLI.

Parameters:

• project_dir (Path | str)

• profile_name (str)

• experiment (str)

• cli_overrides (dict[str, Any] | None)

• user_config_path (Path | None)

Return type:

ResolvedConfig

pstrain.api.config.CURRENT_CONFIG_VERSION

Current version number for the canonical configuration schema.

User settings

~/.pstrain/config.yaml holds both semantic overrides and presentation preferences. PSTRAIN_USER_CONFIG selects an alternate file for both readers. For example:

config_version: 1
features:
  alpha: 0.9
training:
  tied:
    max_iterations: 7
json_output:
  indent: 4

get_user_config().save() preserves the semantic blocks while saving changed preferences. It validates the document and replaces the file atomically; omitted semantic blocks remain omitted, so saving preferences does not freeze unrelated defaults. Project and experiment overlays accept semantic settings only. Unknown fields in a versioned user document are errors.

The legacy defaults block remains readable for compatibility but is not a training override. Use features, training, split, runner, sharding, and alignment for effective settings. Saving a legacy document writes version 1 and preserves the legacy fields that the resolver actually consumed, such as features.num_ceps as features.ncep.

Exclusion schedules accept positive pass numbers or "*". Numeric strings are normalized to integer pass numbers; aliases for the same pass in one schedule are rejected rather than silently overwriting an exclusion list.