fix(packaging): read __version__ from installed metadata and pin documented install to Python 3.12

[elyasmnvidian]

python - <<'PY'
from importlib.metadata import version

import switchyard

print("module  ", switchyard.__version__)
print("metadata", version("nemo-switchyard"))
PY

The package reports two different versions:

module   0.1.0
metadata 0.2.0

switchyard/__init__.py contains its own version literal, while wheel metadata reads the
version from pyproject.toml. A release update can change one copy and leave the other behind.

The documented tool install has a separate packaging problem:

uv tool install "nemo-switchyard[cli,server]"

When the default interpreter is Python 3.11, uv rejects the install:

No solution found when resolving dependencies:
Because only nemo-switchyard[cli]==0.2.0 is available and the current Python
version (3.11.15) does not satisfy Python>=3.12, all versions of
nemo-switchyard[cli] cannot be used.

Fix

switchyard.__version__ now reads the installed nemo-switchyard metadata. When no installed
metadata exists, it returns 0.0.0+unknown instead of an unrelated release number.

The dev-wheel helper now writes only pyproject.toml. It rejects any distribution name other
than nemo-switchyard before changing the file, because runtime version readers use that public
distribution name. The README and installation guides now select Python 3.12 explicitly.

Evidence

Clean installs on Python 3.12 and 3.14 report the same value from both readers:

module   0.2.0
metadata 0.2.0

An invalid release-helper name returns exit code 2 before pyproject.toml changes:

$ python scripts/release/set_dev_wheel_version.py 0.0.1.dev0 --package-name another-package
error: package name must be 'nemo-switchyard'

No performance behavior changes in this PR.

How tested

uv run pytest tests/test_dev_wheel_versioning.py tests/test_version_package_name.py -v

The tests cover installed metadata, missing metadata, the canonical dev-wheel name, and rejection
of another package name without changing pyproject.toml. The clean-package import check also ran
with Python 3.12 and Python 3.14.

Compatibility

switchyard.__version__ remains a string. Official release and dev-wheel builds still use
nemo-switchyard; passing another name to the internal release helper now returns an error.

[coderabbitai]

Walkthrough

CLI installation documentation and drift tests now specify Python 3.12. Runtime version reporting reads installed distribution metadata with a source fallback. Dev wheel stamping updates only pyproject.toml, with updated tests.

Changes

Version and installation updates

Layer / File(s)	Summary
Runtime version metadata and release stamping scripts/release/set_dev_wheel_version.py, switchyard/__init__.py, tests/test_dev_wheel_versioning.py, tests/test_version_package_name.py	Release stamping now updates only project metadata. switchyard.__version__ reads installed package metadata and falls back to 0.0.0+unknown. Tests cover both behaviors.
Python 3.12 CLI installation README.md, docs/cli_reference.md, docs/getting_started.md, tests/getting_started/test_getting_started.py, tests/readme/test_readme.py	CLI installation commands now include --python 3.12. Documentation drift tests assert the updated commands.

Estimated code review effort: 2 (Simple) | ~10 minutes

Poem

A rabbit checks the version line,
“Metadata now will keep it fine.”
Python twelve guides tools to land,
Docs and tests march paw in hand.
Hop, hop—the release path is clear!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes both main changes: metadata-based version handling and Python 3.12 installation pinning.

✨ Finishing Touches 💡 1

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch emehtabuddin/oss-020-version-single-source

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/release/set_dev_wheel_version.py`:
- Around line 81-84: Enforce the canonical `nemo-switchyard` distribution name
in the release version-update flow around `update_pyproject`: reject any
`--package-name` value that differs from `nemo-switchyard` before performing
runtime version lookups or file updates. Preserve the existing behavior for the
canonical name and cover the rejection path in the relevant tests.

In `@switchyard/__init__.py`:
- Around line 205-208: Add an explicit str annotation for the public module
attribute __version__ before the try block, while preserving its existing
assignments from _metadata.version and the fallback value in both exception
branches.

In `@tests/test_version_package_name.py`:
- Around line 45-53: Add a pytest test alongside
test_dunder_version_matches_installed_metadata that uses pytest-mock to patch
switchyard._metadata.version to raise PackageNotFoundError, reloads switchyard,
and asserts __version__ equals "0.0.0+unknown". Remove the no-cover exemption
from the source-tree fallback in switchyard.__init__.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 8dc82152-2e86-4d5e-bc77-47ca2a18473c

📥 Commits

Reviewing files that changed from the base of the PR and between 3b9fbd5 and bc6acec.

📒 Files selected for processing (9)

• README.md
• docs/cli_reference.md
• docs/getting_started.md
• scripts/release/set_dev_wheel_version.py
• switchyard/__init__.py
• tests/getting_started/test_getting_started.py
• tests/readme/test_readme.py
• tests/test_dev_wheel_versioning.py
• tests/test_version_package_name.py

💤 Files with no reviewable changes (1)

• tests/test_dev_wheel_versioning.py

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA-NeMo.github.io/Switchyard/pr-preview/pr-255/
Built to branch gh-pages at 2026-08-04 18:07 UTC. Preview will be ready when the GitHub Pages deployment is complete.