# Version Synchronization Requirements Across Agent-Reach's pyproject.toml, __init__.py, and Tests

> Discover Agent-Reach's version synchronization needs for pyproject.toml, __init__.py, and tests. Ensure consistency and prevent release errors with our guide.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: internals
- Published: 2026-07-03

---

**Agent-Reach requires developers to manually synchronize the version string "1.5.0" across [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml), [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py), and [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py), using the test suite as an automated safety net to detect mismatches before release.**

In the Panniantong/Agent-Reach repository, version consistency is maintained through a manual three-file update process. The project stores its release identifier in the package metadata, a runtime module constant, and test assertions, requiring careful coordination during each release to ensure all components report the same version number.

## Where Version Numbers Are Defined

Agent-Reach maintains its version in three distinct locations, each serving a specific purpose in the build, runtime, and validation lifecycle.

### pyproject.toml – The Canonical Source

In [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml), the version is declared as a literal string that packaging tools consume:

```toml
version = "1.5.0"

```

This value serves as the **single source of truth** for pip, build, and other PEP 517-compliant tools when installing or distributing the package.

### agent_reach/__init__.py – The Runtime Constant

The [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) file exposes the version at runtime through the standard `__version__` attribute:

```python
__version__ = "1.5.0"

```

The CLI and other runtime components import this constant via `from agent_reach import __version__` to display version information to users and perform version comparisons.

### tests/test_cli.py – The Validation Layer

The test suite contains hardcoded assertions that validate version logic and enforce synchronization:

```python
assert cli._is_newer_version("1.5.0", "1.4.2") is True
assert cli._is_newer_version("1.5.0", "1.5.0") is False

```

These tests fail immediately if the version literals in the source files diverge from the expected values, preventing inconsistent releases from being merged.

## The Synchronization Workflow

Because Agent-Reach does not implement automated version propagation scripts, the synchronization process is **human-driven** and follows this mandatory sequence:

1. **Update [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)** – Bump the version string when preparing a new release.
2. **Mirror to [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py)** – Copy the identical literal string into [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) as the `__version__` constant.
3. **Update test assertions** – Ensure [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) reflects the new version in its comparison logic.
4. **Validate with pytest** – Run `pytest tests/ -v` to confirm the `_is_newer_version` function and related version tests pass.

This workflow ensures that any mismatch between the packaging metadata and runtime code triggers an immediate test failure, acting as a protective barrier against version drift.

## Accessing and Comparing Versions in Your Code

You can retrieve the current version from user code by importing the package constant:

```python
from agent_reach import __version__

print(f"Agent-Reach version: {__version__}")

# Output: Agent-Reach version: 1.5.0

```

For checking update availability against remote versions, use the CLI's comparison helper:

```python
from agent_reach.cli import _is_newer_version
from agent_reach import __version__

if _is_newer_version(remote="1.5.1", local=__version__):
    print("A newer release is available!")
else:
    print("You are up-to-date.")

```

## Summary

- **Three locations require updates**: [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) (packaging), [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) (runtime), and [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) (validation).
- **Manual synchronization**: Developers must copy the version string literally between files; no automated propagation exists.
- **Test safety net**: The `_is_newer_version` assertions in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) catch mismatches during the CI/CD process.
- **Current version**: As of the latest release, all three files specify version "1.5.0".

## Frequently Asked Questions

### What happens if I forget to update one of the three version locations?

If the version string in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) or [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) differs from the hardcoded values in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py), the test suite will fail when running `pytest`. Specifically, assertions testing the `_is_newer_version` function will raise errors, alerting maintainers to the inconsistency before the code is merged.

### Why does Agent-Reach use manual version updates instead of dynamic configuration?

The project employs a **literal string approach** rather than dynamic parsing or automated rewriting scripts. This simplicity ensures that the version is explicitly visible in source control and prevents build-time dependencies from complicating the installation process. The trade-off requires manual vigilance, which is enforced by the test suite.

### How does the CLI access the version number for user display?

The CLI module imports the version constant directly from the package root using `from agent_reach import __version__`. This ensures that the version reported by command-line tools matches the value defined in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) and stays synchronized with the package metadata in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml).

### Can I check programmatically if a newer version of Agent-Reach is available?

Yes. Import the `_is_newer_version` function from `agent_reach.cli` and compare your current `__version__` against a remote version string. This helper returns `True` if the remote version is newer, allowing you to implement custom update notifications in your applications.