feat(audio-alm): agent-ready ALM data-builder and pretrain stages

[shubhamNvidia]

Summary

Makes the ALM (audio-language-model) data-pipeline stages agent-ready. Additive only.

• alm/alm_data_builder.py, alm/alm_data_overlap.py, alm/pretrain/extraction.py, alm/pretrain/io.py, alm/pretrain/planning.py — subclass AgentReady and add describe() / StageContract declaring each stage's reads/writes; some hardcoded keys made configurable. Core data-building / planning / IO logic is unchanged.

Notes for reviewers

• Additive, backward compatible; no runtime behavior change expected.
• Worth a look: that each new describe() matches what the stage actually reads/writes.

Test plan

• pytest tests/stages/audio/alm -q

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

This PR makes eight ALM/pretrain audio pipeline stages "agent-ready" by adding an AgentReady mixin, implementing describe() on each stage, and introducing two new modules (_agent_ready.py, _residency.py). It also makes previously hardcoded data keys configurable via constructor fields. The core processing logic is unchanged.

• _agent_ready.py defines StageContract, IOSpec, Gates, and the AgentReady mixin. Several contract accuracy issues exist across stages: ALMDataOverlapStage underreports its writes (eight keys beyond filtered_windows_key), ALMDataBuilderStage omits swift_audio_filepath_key from reads, ManifestReader declares no writes at all, and PreserveByValueStage returns batch_only=False despite BATCH_ONLY = True.
• _residency.py provides reusable audio residency utilities for stages that accept either file paths or in-memory waveforms.

Confidence Score: 3/5

Runtime behavior is unchanged, but several describe() contracts misrepresent what stages actually read/write, which will cause agents to mis-sequence or misconfigure pipelines once the agent layer is activated.

The PR accumulates multiple incorrect describe() contracts: ManifestReader declares no writes at all, PreserveByValueStage advertises batch_only=False while process() raises unconditionally, ALMDataOverlapStage underreports its written keys by eight fields, and ALMDataBuilderStage omits a consumed key from its reads.

nemo_curator/stages/audio/common.py (ManifestReader missing writes, PreserveByValueStage batch_only mismatch), nemo_curator/stages/audio/alm/alm_data_overlap.py (underreported writes), nemo_curator/stages/audio/alm/alm_data_builder.py (missing reads key)

Important Files Changed

Filename	Overview
nemo_curator/stages/audio/_agent_ready.py	New file: introduces AgentReady mixin, StageContract, and supporting dataclasses. describe_static() imports from a non-existent _agent_registry module (flagged in previous review). to_json_schema silently drops default: None (previously flagged).
nemo_curator/stages/audio/_residency.py	New file: audio residency utilities. Temp file leak when sf.write raises was flagged in a previous review; logic is otherwise sound.
nemo_curator/stages/audio/alm/alm_data_builder.py	Adds AgentReady mixin and describe(). Reads contract omits swift_audio_filepath_key (flagged in prior review); core logic unchanged.
nemo_curator/stages/audio/alm/alm_data_overlap.py	Adds AgentReady mixin and describe(). Writes contract underreports eight keys and stats is missing from reads (flagged in prior review).
nemo_curator/stages/audio/alm/pretrain/extraction.py	Adds AgentReady mixin and describe(). Contract looks accurate with correct dry_run-conditional gates.
nemo_curator/stages/audio/alm/pretrain/io.py	Adds AgentReady mixin and describe() to three stages. Contracts look correct. Core I/O logic unchanged.
nemo_curator/stages/audio/alm/pretrain/planning.py	Adds AgentReady mixin and describe() to three planning stages. Contracts look accurate. Core planning logic unchanged.
nemo_curator/stages/audio/common.py	Adds AgentReady mixin and describe() to common stages. PreserveByValueStage.describe() returns batch_only=False despite BATCH_ONLY = True; ManifestReader.describe() declares no writes.

_{Reviews (2): Last reviewed commit: "fix(audio): match _residency.py to found..." | Re-trigger Greptile}

[greptile-apps]

to_json_schema silently drops default: None from the JSON schema

The guard if p.default is not None skips emitting "default": null for parameters whose true default is None. An agent reading the schema cannot distinguish "no default declared" from "default is None", and may incorrectly treat those parameters as required. Using a sentinel (e.g. _MISSING = object()) in ParamSpec to represent "no default" would preserve the distinction.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!