Define public API and SemVer compatibility policy for NeMo Agent Toolkit plugin authors

[bbednarski9]

How would you describe the priority of this documentation request

High

Describe the future/missing documentation

As we start supporting new 3rd party owned plugin repos, we should have documentation that defines the NeMo Agent Toolkit public API compatibility policy, especially for external plugin authors.

Follow-up from #1952 / the nat.plugin_api stabilization work: nat.plugin_api now gives plugin authors a stable import facade, but the broader SemVer policy is still not fully documented.

The docs should clarify:

• What counts as public API:
  • nat.plugin_api exports
  • documented plugin entry points
  • documented CLI/config behavior
  • selected testing helpers such as nat.test.ToolTestRunner, if we intend those to be stable
• What is private/internal:
  • deep implementation modules
  • undocumented runtime internals
  • deferred extension points that are not promoted into nat.plugin_api
• What changes are allowed by version type:
  • patch releases: compatible fixes only
  • minor releases: additive public APIs and compatible behavior changes
  • major releases: removals, incompatible signature changes, removed compatibility shims, required config changes
• Deprecation lifecycle for public APIs:
  • when to emit warnings
  • where migration guidance must be documented
  • how long deprecated APIs should remain available
  • when compatibility shims can be removed
• How to promote a deferred API into the public facade:
  • update nat.plugin_api.__all__
  • update the public API contract tests
  • update Plugin API docs
  • add migration/deprecation notes when needed
• How external packages should declare dependencies on NAT:
  • recommended ~=major.minor constraints
  • guidance for packages that depend on newly added public APIs

This should also explain that installed plugins are trusted Python code. SemVer compatibility defines supported import and behavior contracts; it does not make arbitrary third-party plugins safe to install or execute.

Where have you looked?

Where have you looked?

• docs/source/extend/plugin-api.md
• docs/source/extend/plugins.md
• docs/source/resources/migration-guide.md
• docs/source/get-started/tutorials/create-a-new-workflow.md
• packages/nvidia_nat_core/tests/nat/test_plugin_api.py
• packages/nvidia_nat_core/src/nat/utils/decorators.py

Code of Conduct

• I agree to follow this project's Code of Conduct
• I have searched the open documentation issues and have found no duplicates for this bug report