Agent Reach Version Management: How to Sync `pyproject.toml` and Package Initialization

Agent Reach manages versions manually across two locations—the version field in pyproject.toml and the __version__ constant in agent_reach/__init__.py—with automated tests ensuring they never diverge.

The Agent Reach Python package follows a straightforward but strict strategy to keep its version number consistent between build metadata and runtime code. This dual-location approach ensures that package managers, CLI tools, and internal checks all report identical version information.

Where Agent Reach Defines Its Version

According to the Panniantong/Agent-Reach source code, version information lives in two specific files:

Canonical Version in pyproject.toml

The authoritative version string resides in the top-level pyproject.toml file at line 3:

[project]
name = "agent-reach"
version = "1.5.0"

This value drives the release pipeline. When publishing to PyPI, build tools read this field to tag the distribution.

Runtime Version in __init__.py

The same version is exposed to Python code through the module-level constant __version__ in agent_reach/__init__.py at line 4:

# agent_reach/__init__.py

__version__ = "1.5.0"

This constant enables runtime version inspection without parsing TOML files.

Why Agent Reach Maintains Two Version Locations

The separation serves distinct technical purposes:

• Build and publish workflows depend on pyproject.toml for package metadata
• CLI commands like agent-reach version and check-update read __version__ for immediate output
• Import-time access allows other Python code to check compatibility via from agent_reach import __version__

How Agent Reach Prevents Version Drift

The project guards against mismatch through automated testing. The test suite in tests/test_cli.py asserts that the two version values remain identical:

# Conceptual representation of the sync test

def test_version_matches_pyproject():
    from agent_reach import __version__
    assert __version__ == get_version_from_pyproject()

If a developer updates pyproject.toml without mirroring the change in __init__.py, CI fails immediately. This prevents releases with inconsistent version reporting.

Accessing the Version in Your Code

Retrieve the Agent Reach version at runtime with a simple import:

from agent_reach import __version__

print(f"Agent Reach v{__version__}")

# Output: Agent Reach v1.5.0

The CLI leverages this same constant:

$ agent-reach version
Agent Reach v1.5.0

Release Workflow for Agent Reach Versions

To prepare a new release, developers execute these steps:

1. Update pyproject.toml—modify the version field to the new release number
2. Mirror to __init__.py—copy the identical string to __version__
3. Verify via tests—run tests/test_cli.py to confirm synchronization
4. Commit and tag—the synchronized state is now safe to publish

This manual-but-tested approach avoids complex single-source versioning schemes while maintaining reliability.

Summary

• Agent Reach version management relies on dual definitions in pyproject.toml and agent_reach/__init__.py
• pyproject.toml line 3 contains the canonical version for package publishing
• __init__.py line 4 exposes __version__ for runtime and CLI access
• tests/test_cli.py enforces synchronization through automated assertions
• Both locations currently hold "1.5.0"

Frequently Asked Questions

What happens if the versions in pyproject.toml and __init__.py differ?

The test suite in tests/test_cli.py detects the mismatch and causes CI to fail. This prevents publishing or deploying a release with inconsistent version reporting between package metadata and runtime behavior.

Why doesn't Agent Reach use a single-source versioning tool?

The project opts for manual synchronization with test coverage. This avoids dependencies on dynamic versioning tools like setuptools-scm or complex __version__ derivation logic, keeping the build process transparent and debuggable.

How can I check the installed Agent Reach version programmatically?

Import the __version__ constant directly from the package:

from agent_reach import __version__
print(__version__)  # "1.5.0"

This reads the value defined in agent_reach/__init__.py without file system access to pyproject.toml.

Where does the CLI read its version output from?

The agent-reach version command sources its output from __version__ in agent_reach/__init__.py. This ensures the reported version matches what other Python code would observe when importing the package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}