Version Tracking for align-system Experiments

[PaulHax]

Experiments produce input_output.json files without version information, making it impossible to trace which version of align-system generated the results.

Proposal

Add a single version field to input_output.json files using setuptools-scm for consistent version formatting.

Implementation

Single Version Field

Add one field at the root of input_output.json:

{
  "version": "0.5.9.dev3+g1234567.d20250118",
  "results": [
    // existing experiment results
  ]
}

Note: This changes the root structure from an array to an object. Current format is [{...}, {...}], new format would be {"version": "...", "results": [{...}, {...}]}.

Could also add another JSON file version.json??

Version formats:

• Tagged release: 0.5.9
• Development: 0.5.10.dev3+g1234567 (3 commits after tag)
• Dirty working dir: 0.5.9+d20250118 (uncommitted changes with date)
• Dev + dirty: 0.5.10.dev3+g1234567.d20250118

Version Retrieval Using setuptools-scm

Add setuptools-scm as dependancy.

Create align_system/utils/version.py:

from importlib.metadata import version, PackageNotFoundError

def get_version():
    """Get version using setuptools-scm format."""
    try:
        # Try using setuptools-scm for development installs
        from setuptools_scm import get_version as scm_get_version

        # Gets version from git tags/commits with proper formatting
        # Automatically handles dirty state with date
        return scm_get_version(root='../..', relative_to=__file__)

    except (ImportError, LookupError):
        # Fallback to installed package version
        try:
            return version("align-system")
        except PackageNotFoundError:
            return "unknown"

Implementation Steps

1. Add setuptools-scm to pyproject.toml dependencies
2. Create align_system/utils/version.py
3. Update output writers to include version field
4. Test with development checkouts
5. Update documentation?