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

> Agent Reach syncs package versions between pyproject.toml and __init__.py using automated tests to prevent divergence. Learn how this manual yet reliable strategy ensures version consistency.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: best-practices
- Published: 2026-08-05

---

**Agent Reach manages versions manually across two locations—the `version` field in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and the `__version__` constant in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)

The authoritative version string resides in the top-level **[`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)** file at **line 3**:

```toml
[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`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py)

The same version is exposed to Python code through the module-level constant **`__version__`** in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) at **line 4**:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py)** asserts that the two version values remain identical:

```python

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) without mirroring the change in [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__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:

```python
from agent_reach import __version__

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

# Output: Agent Reach v1.5.0

```

The CLI leverages this same constant:

```bash
$ 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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)**—modify the `version` field to the new release number
2. **Mirror to [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py)**—copy the identical string to `__version__`
3. **Verify via tests**—run [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)
- **[`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) line 3** contains the canonical version for package publishing
- **[`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) line 4** exposes `__version__` for runtime and CLI access
- **[`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) and [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) differ?

The test suite in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```

This reads the value defined in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) without file system access to [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py). This ensures the reported version matches what other Python code would observe when importing the package.