# Agent Reach Version Synchronization Requirements: pyproject.toml, __init__.py, and test_cli.py

> Synchronize Agent Reach versions across pyproject.toml, __init__.py, and test_cli.py for consistent packaging, runtime, and CLI outputs. Ensure accurate versioning.

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

---

**Agent Reach requires the version string to be synchronized across three files—[`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)—to ensure consistent versioning across packaging, runtime, and CLI outputs.**

In the Panniantong/Agent-Reach repository, maintaining identical version identifiers prevents mismatched release information and CI failures. The package relies on a manual triple-point validation system where build metadata, runtime constants, and test assertions must contain the exact same version string.

## The Three Critical Files

Agent Reach enforces version consistency through three specific locations. Each serves a distinct purpose in the package lifecycle, and divergence between them causes immediate test failures.

### pyproject.toml (Build Metadata)

The [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) file at the repository root defines the **build metadata** consumed by Hatchling. At line 3, the version declaration determines what `pip` and package indexes publish:

```toml
[project]
version = "1.5.0"

```

This static assignment controls the wheel version and PyPI distribution artifacts.

### agent_reach/__init__.py (Runtime Constant)

The [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) file exposes the **`__version__`** runtime constant at line 4:

```python
__version__ = "1.5.0"

```

Downstream code accesses this via `agent_reach.__version__`, and the CLI imports this constant to generate its `--version` output.

### tests/test_cli.py (Verification Suite)

The test suite validates synchronization through [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py). The `TestCLI.test_version` method (lines 15–22) executes the CLI and asserts that the output contains the expected version pattern:

```python
def test_version(self, capsys):
    with pytest.raises(SystemExit) as exc_info:
        with patch("sys.argv", ["agent-reach", "version"]):
            main()
    assert exc_info.value.code == 0
    captured = capsys.readouterr()
    assert "Agent Reach v" in captured.out

```

This test ensures that the runtime version matches the user-facing CLI output, preventing releases where the build and runtime versions diverge.

## How Version Propagation Works

The version flows through the codebase in a specific chain that creates testable dependencies:

1. **[`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)** declares the static version for Hatchling builds
2. **[`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py)** stores the runtime constant imported by the CLI
3. **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** (line 58) registers the `--version` argument using the `__version__` constant:

```python
parser.add_argument(
    "--version",
    action="version",
    version=f"Agent Reach v{__version__}"
)

```

When users execute `agent-reach version`, the CLI prints `Agent Reach v1.5.0` by reading directly from [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py). Because the test suite verifies this output against the actual runtime behavior, any discrepancy between the build metadata and runtime code immediately surfaces as a test failure.

## Practical Synchronization Examples

When releasing a new version, update all three locations simultaneously:

**In [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml):**

```toml
[project]
version = "1.6.0"

```

**In [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py):**

```python
__version__ = "1.6.0"

```

**Verification via CLI:**

```bash
$ agent-reach version
Agent Reach v1.6.0

```

The test suite automatically confirms alignment. If the CLI output does not match the expected pattern, `pytest` will report the assertion failure in [`test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/test_cli.py), preventing release of inconsistent artifacts.

## Summary

- **Three files must match**: [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) (build), [`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) (verification)
- **Single source of truth**: While [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) controls packaging, [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py) controls runtime behavior
- **Test enforcement**: The `test_version` test in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) guarantees that CLI output matches the package version
- **Failure mode**: Divergent versions cause CI failures and user confusion when `pip` reports one version but `agent-reach --version` reports another

## Frequently Asked Questions

### What happens if pyproject.toml and __init__.py versions diverge?

The package will build with one version (from [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml)) but report a different version at runtime (from [`__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/__init__.py)). This causes the `test_version` test in [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) to fail because the CLI output will not match the expected pattern, blocking the release pipeline and preventing inconsistent deployments.

### Why does Agent Reach use manual version synchronization instead of dynamic versioning?

The repository uses static version strings in all three locations to maintain explicit, readable version declarations. While tools like `hatch-vcs` can automate versioning from Git tags, the Panniantong/Agent-Reach codebase prefers explicit synchronization to ensure that the runtime `__version__`, build metadata, and test assertions remain perfectly aligned without additional build dependencies.

### How do I update the version for a new release?

Update the version string in all three locations simultaneously: modify `version` in [`pyproject.toml`](https://github.com/Panniantong/Agent-Reach/blob/main/pyproject.toml) (line 3), `__version__` in [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) (line 4), and verify that [`tests/test_cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/tests/test_cli.py) expects the new version in its assertion. Run the test suite to confirm `pytest` passes the version check before committing the release.

### Where does the CLI read its version information?

The CLI implementation in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) imports `__version__` directly from [`agent_reach/__init__.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/__init__.py) and passes it to the `argparse` `--version` action at line 58. This ensures that `agent-reach --version` always reflects the runtime constant rather than the build metadata, creating a dependency that tests enforce.