feat(plugin-api): export the configuration, build, and run surfaces

[DABH]

Description

Third-party plugin packages are asked to import plugin-authoring symbols only from the stable nat.plugin_api facade (per docs/source/extend/third-party-plugins.md). However, plugins that programmatically load, build, or drive workflows — front ends, execution instrumentation, and test harnesses — currently have to import implementation modules for every step of that flow:

• Config (nat.data_models.config) plus load_config, PluginTypes, and discover_and_register_plugins (nat.runtime.loader) to discover installed plugins and produce a validated configuration object.
• WorkflowBuilder (nat.builder.workflow_builder) to build the configured workflow.
• Runner (nat.runtime.runner) and ExporterManager (nat.observability.exporter_manager) to drive a run the same way Workflow.run does.

On top of that, the built Workflow keeps its entry function private (self._entry_fn), so a caller that wants to construct a Runner for it, or introspect the workflow's input and output contracts, has to reach into a private attribute.

This change is purely additive:

• Re-export the symbols above through nat.plugin_api and extend __all__.
• Add a public read-only entry_fn property to Workflow with a docstring; internal call sites are unchanged.
• Pin the new symbols in EXPECTED_PLUGIN_API_EXPORTS.
• Add a consumer-style test that, importing only from nat.plugin_api, registers a function, loads a minimal config, builds it with WorkflowBuilder, reads workflow.entry_fn, and drives a run with Runner, sourcing the exporter manager from the built workflow's public read-only exporter_manager property the same way Workflow.run does, so the demonstrated pattern preserves configured telemetry exporters.
• Document the new surface in docs/source/extend/plugin-api.md: two new surface-review rows ("Configuration loading and plugin discovery" and "Workflow build and run", both proposed as provisional public, matching the promotion tier of the runtime context access row), a new public-surface bullet, and a reworked WorkflowBuilder note in the private-modules section. The runtime context access row no longer lists exporter management as unpromoted, and the builder-type row no longer describes concrete builders as implementation details — it now points at the "Workflow build and run" row, which also tells callers constructing a Runner directly to source the exporter manager from the built workflow.

Workflow.run remains the simplest way to execute a built workflow. Runner and ExporterManager are exported for callers that need to own the run scope — for example supplying their own ContextState or instrumenting the runner lifecycle — and ExporterManager is the declared type of both the built workflow's public exporter_manager property and Runner's required exporter_manager parameter, so driving a run through the facade needs it importable.

register_front_end and the front-end hosting contract remain deferred; this PR only promotes the objects needed to load a configuration, build it, and drive runs.

No tracking issue exists for this yet; happy to file one if the team prefers.

Testing

• uv run pytest packages/nvidia_nat_core/tests/nat/test_plugin_api.py — 8 passed (includes the new consumer-style test).
• uv run pytest packages/nvidia_nat_core/tests/nat/builder packages/nvidia_nat_core/tests/nat/runtime packages/nvidia_nat_core/tests/nat/middleware packages/nvidia_nat_core/tests/nat/observability — 1341 passed.
• uv run pytest packages/nvidia_nat_core/tests --ignore=packages/nvidia_nat_core/tests/eval/test_eval_callbacks.py --ignore=packages/nvidia_nat_core/tests/nat/finetuning/interfaces/test_trajectory_builder.py — 2585 passed, 236 skipped. The two ignored modules import the eval plugin extra (not installed locally) and fail to collect identically on the base branch.
• uv run pre-commit run yapf --files <touched files> and uv run pre-commit run ruff-check --files <touched files>, uv run python ci/scripts/copyright.py --verify-apache-v2, vale and the markdown-link-check hook on the touched Markdown file, and uv run python ci/scripts/path_checks.py all pass.

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license.
  • Any contribution which contains commits that are not Signed-Off will not be accepted.
• When the PR is ready for review, new or existing tests cover these changes.
• When the PR is ready for review, the documentation is up to date with these changes.

[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.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9d2dfb15-c82e-468c-8c5b-873a09060a7e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}