refactor(core): make release metadata lightweight

Author: reacher-z

pyproject.toml

@@ -34,7 +34,7 @@ Paper = "https://arxiv.org/abs/2605.08703"
 
 [tool.setuptools.dynamic]
 dependencies = { file = ["requirements.txt"] }
-version = { attr = "rewardharness.__version__" }
+version = { attr = "rewardharness._version.__version__" }
 
 [tool.setuptools.packages.find]
 include = ["rewardharness*", "src*"]

rewardharness/__init__.py

@@ -1,10 +1,18 @@
-"""Public package for RewardHarness."""
+"""Public package for RewardHarness with lazy top-level exports."""
 
-from rewardharness.config import RewardHarnessConfig
-from rewardharness.domain import EvaluationExample, EvaluationResult, Preference, ScoreCard
-from rewardharness.evaluation.engine import SubAgent
-from rewardharness.evolution.pipeline import SelfEvolutionPipeline
-from rewardharness.library import Library, LibraryRepository
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from rewardharness._version import __version__
+
+if TYPE_CHECKING:
+    from rewardharness.config import RewardHarnessConfig
+    from rewardharness.domain import EvaluationExample, EvaluationResult, Preference, ScoreCard
+    from rewardharness.evaluation.engine import SubAgent
+    from rewardharness.evolution.pipeline import SelfEvolutionPipeline
+    from rewardharness.library import Library, LibraryRepository
 
 __all__ = [
     "EvaluationExample",
@@ -16,6 +24,32 @@
     "ScoreCard",
     "SelfEvolutionPipeline",
     "SubAgent",
+    "__version__",
 ]
 
-__version__ = "0.2.0rc1"
+_EXPORTS = {
+    "EvaluationExample": ("rewardharness.domain", "EvaluationExample"),
+    "EvaluationResult": ("rewardharness.domain", "EvaluationResult"),
+    "Library": ("rewardharness.library", "Library"),
+    "LibraryRepository": ("rewardharness.library", "LibraryRepository"),
+    "Preference": ("rewardharness.domain", "Preference"),
+    "RewardHarnessConfig": ("rewardharness.config", "RewardHarnessConfig"),
+    "ScoreCard": ("rewardharness.domain", "ScoreCard"),
+    "SelfEvolutionPipeline": ("rewardharness.evolution.pipeline", "SelfEvolutionPipeline"),
+    "SubAgent": ("rewardharness.evaluation.engine", "SubAgent"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Load public objects on first access to keep metadata imports lightweight."""
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attribute = target
+    value = getattr(import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

rewardharness/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the RewardHarness package version."""
+
+__version__ = "0.2.0rc1"

rewardharness/cli.py

@@ -8,16 +8,14 @@
 import logging
 from collections.abc import Sequence
 from pathlib import Path
+from typing import TYPE_CHECKING
 
-from rewardharness import __version__
-from rewardharness.benchmark import run_benchmark
-from rewardharness.clients.endpoints import EndpointPool
-from rewardharness.config import RewardHarnessConfig
-from rewardharness.evaluation.engine import SUBAGENT_MODEL, SubAgent
-from rewardharness.evaluation.router import Router
-from rewardharness.evolution.pipeline import SelfEvolutionPipeline
-from rewardharness.library import Library
+from rewardharness._version import __version__
 from rewardharness.paths import PROJECT_ROOT, default_endpoints_path, default_library_path
+from rewardharness.release import ReleaseIdentity
+
+if TYPE_CHECKING:
+    from rewardharness.config import RewardHarnessConfig
 
 
 def _path(value: str) -> Path:
@@ -41,6 +39,7 @@ def build_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     subparsers.add_parser("check", help="validate local credentials and endpoints")
+    subparsers.add_parser("release-status", help="show canonical package and release identifiers")
 
     inspect_parser = subparsers.add_parser("inspect", help="inspect a Library registry")
     inspect_parser.add_argument("--library-dir", default=str(default_library_path()))
@@ -68,10 +67,14 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def _load_config(path: str) -> RewardHarnessConfig:
+    from rewardharness.config import RewardHarnessConfig
+
     return RewardHarnessConfig.from_yaml(_path(path))
 
 
 def _inspect(library_dir: str, validate: bool = False) -> int:
+    from rewardharness.library import Library
+
     library = Library(str(_path(library_dir)))
     if validate:
         for name in library.registry:
@@ -81,6 +84,8 @@ def _inspect(library_dir: str, validate: bool = False) -> int:
 
 
 def _evolve(args: argparse.Namespace) -> int:
+    from rewardharness.evolution.pipeline import SelfEvolutionPipeline
+
     config = _load_config(args.config)
     pipeline = SelfEvolutionPipeline(config, args.library_dir, args.results_dir)
     iterations = args.max_iters or config.evolution.max_iterations
@@ -92,12 +97,19 @@ def _evolve(args: argparse.Namespace) -> int:
 
 
 def _benchmark(args: argparse.Namespace) -> int:
+    from rewardharness.benchmark import run_benchmark
+
     config = _load_config(args.config)
     run_benchmark(config.to_legacy_dict(), args.library_dir, args.results_dir)
     return 0
 
 
 def _score_pair(args: argparse.Namespace) -> int:
+    from rewardharness.clients.endpoints import EndpointPool
+    from rewardharness.evaluation.engine import SUBAGENT_MODEL, SubAgent
+    from rewardharness.evaluation.router import Router
+    from rewardharness.library import Library
+
     library = Library(str(_path(args.library_dir)))
     context = Router(library).prepare_context(args.prompt)
     pool = EndpointPool(endpoints_file=str(_path(args.endpoints)))
@@ -126,6 +138,9 @@ def main(argv: Sequence[str] | None = None) -> int:
         from rewardharness.diagnostics import main as diagnostics_main
 
         return diagnostics_main()
+    if args.command == "release-status":
+        print(json.dumps(ReleaseIdentity.current().to_dict(), indent=2, sort_keys=True))
+        return 0
     if args.command == "inspect":
         return _inspect(args.library_dir)
     if args.command == "validate-library":

rewardharness/release.py

@@ -0,0 +1,85 @@
+"""Release identity and tag validation utilities."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from collections.abc import Sequence
+from dataclasses import asdict, dataclass
+
+from rewardharness._version import __version__
+
+_PACKAGE_VERSION = re.compile(r"^(?P<base>\d+\.\d+\.\d+)(?:(?P<stage>a|b|rc)(?P<number>\d+))?$")
+_TAG_VERSION = re.compile(r"^v(?P<base>\d+\.\d+\.\d+)(?:-(?P<stage>a|b|rc)(?P<number>\d+))?$")
+
+
+def package_version_to_tag(version: str) -> str:
+    """Convert a PEP 440 package version to the repository tag convention."""
+    match = _PACKAGE_VERSION.fullmatch(version)
+    if match is None:
+        raise ValueError(f"Unsupported package version: {version!r}")
+    suffix = ""
+    if match["stage"]:
+        suffix = f"-{match['stage']}{match['number']}"
+    return f"v{match['base']}{suffix}"
+
+
+def tag_to_package_version(tag: str) -> str:
+    """Convert a repository release tag to its PEP 440 package version."""
+    match = _TAG_VERSION.fullmatch(tag)
+    if match is None:
+        raise ValueError(f"Unsupported release tag: {tag!r}")
+    suffix = ""
+    if match["stage"]:
+        suffix = f"{match['stage']}{match['number']}"
+    return f"{match['base']}{suffix}"
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseIdentity:
+    """Canonical identifiers shared by Git, GitHub Releases, and PyPI."""
+
+    package_version: str
+    tag: str
+    prerelease: bool
+    pypi_url: str
+
+    @classmethod
+    def current(cls) -> ReleaseIdentity:
+        match = _PACKAGE_VERSION.fullmatch(__version__)
+        if match is None:
+            raise RuntimeError(f"Invalid package version: {__version__!r}")
+        tag = package_version_to_tag(__version__)
+        return cls(
+            package_version=__version__,
+            tag=tag,
+            prerelease=bool(match["stage"]),
+            pypi_url=f"https://pypi.org/project/rewardharness/{__version__}/",
+        )
+
+    def validate_tag(self, tag: str) -> None:
+        actual_version = tag_to_package_version(tag)
+        if actual_version != self.package_version:
+            raise ValueError(
+                f"Tag {tag!r} resolves to {actual_version!r}; "
+                f"package version is {self.package_version!r}"
+            )
+
+    def to_dict(self) -> dict[str, str | bool]:
+        return asdict(self)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--check-tag", metavar="TAG")
+    args = parser.parse_args(argv)
+    identity = ReleaseIdentity.current()
+    if args.check_tag:
+        identity.validate_tag(args.check_tag)
+    print(json.dumps(identity.to_dict(), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/README.md

@@ -1,6 +1,6 @@
 # Tests
 
-Fully mocked end-to-end test suite (**138 tests**, runs in a few seconds) — no GPU,
+Fully mocked end-to-end test suite (**154 tests**, runs in a few seconds) — no GPU,
 no network, no API keys, and no real Gemini calls. Install development tooling
 from `requirements-dev.txt` before running the complete quality gate.
 
@@ -23,6 +23,7 @@ make test
 | `test_pipeline.py` | `SelfEvolutionPipeline.evolve` over 2 iterations — separate skill/tool rollback, `>= prev - margin` keep condition, checkpoint write, val-acc regression triggers rollback. |
 | `test_check_env.py` | `scripts/check_env.py::_probe_one` — `/v1/models` body parsing for the VLM-swap mismatch detection added in iter 130. |
 | `test_public_api.py` | Typed v0.2 API, schema v2, compatibility imports, config validation, and path safety. |
+| `test_release.py` | Lazy package imports, canonical PyPI/tag identity, and release-status CLI contracts. |
 
 Everything that touches an external service (Gemini, vLLM, Hugging Face) is mocked with `unittest.mock`. If a test ever makes a real network call, it's a regression — please open an issue.
 

tests/test_release.py

@@ -0,0 +1,89 @@
+"""Tests for lightweight imports and canonical release identity."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+import pytest
+
+import rewardharness
+import rewardharness.release as release_module
+from rewardharness.cli import main as cli_main
+from rewardharness.release import (
+    ReleaseIdentity,
+    package_version_to_tag,
+    tag_to_package_version,
+)
+from rewardharness.release import main as release_main
+
+
+@pytest.mark.parametrize(
+    ("package_version", "tag"),
+    [
+        ("1.2.3", "v1.2.3"),
+        ("1.2.3a1", "v1.2.3-a1"),
+        ("1.2.3b2", "v1.2.3-b2"),
+        ("1.2.3rc4", "v1.2.3-rc4"),
+    ],
+)
+def test_release_version_round_trip(package_version, tag):
+    assert package_version_to_tag(package_version) == tag
+    assert tag_to_package_version(tag) == package_version
+
+
+@pytest.mark.parametrize("value", ["1.2", "v1.2.3", "1.2.3-dev"])
+def test_package_version_rejects_unsupported_values(value):
+    with pytest.raises(ValueError, match="Unsupported package version"):
+        package_version_to_tag(value)
+
+
+@pytest.mark.parametrize("value", ["1.2.3", "v1.2", "v1.2.3-dev1"])
+def test_tag_rejects_unsupported_values(value):
+    with pytest.raises(ValueError, match="Unsupported release tag"):
+        tag_to_package_version(value)
+
+
+def test_current_release_identity_and_tag_validation():
+    identity = ReleaseIdentity.current()
+    assert identity.package_version == "0.2.0rc1"
+    assert identity.tag == "v0.2.0-rc1"
+    assert identity.prerelease is True
+    identity.validate_tag(identity.tag)
+    with pytest.raises(ValueError, match="package version"):
+        identity.validate_tag("v0.2.0-rc2")
+
+
+def test_release_status_cli(capsys):
+    assert cli_main(["release-status"]) == 0
+    assert json.loads(capsys.readouterr().out)["tag"] == "v0.2.0-rc1"
+
+
+def test_release_module_cli_validates_tag(capsys):
+    assert release_main(["--check-tag", "v0.2.0-rc1"]) == 0
+    assert json.loads(capsys.readouterr().out)["package_version"] == "0.2.0rc1"
+
+
+def test_release_identity_rejects_invalid_canonical_version(monkeypatch):
+    monkeypatch.setattr(release_module, "__version__", "invalid")
+    with pytest.raises(RuntimeError, match="Invalid package version"):
+        ReleaseIdentity.current()
+
+
+def test_top_level_exports_are_lazy_and_discoverable():
+    assert rewardharness.Preference.A.value == "A"
+    assert "Preference" in dir(rewardharness)
+    missing_name = "not_a_public_export"
+    with pytest.raises(AttributeError, match="has no attribute"):
+        getattr(rewardharness, missing_name)
+
+
+def test_package_import_does_not_eagerly_load_heavy_dependencies():
+    code = (
+        "import sys, rewardharness; "
+        "assert rewardharness.__version__ == '0.2.0rc1'; "
+        "assert 'datasets' not in sys.modules; "
+        "assert 'transformers' not in sys.modules"
+    )
+    subprocess.run([sys.executable, "-c", code], check=True)