Add flexible JSON version validation with VALIDATE_JSON_VERSION config

The previous JSON version check required exact version matches, which
caused issues when loading data saved with different dev builds (e.g.,
1.2.1.dev1534+g12345 vs 1.2.1.dev1600+gabcde from hatch-vcs).

This change:
- Adds VALIDATE_JSON_VERSION config option to disable version checking
- Allows compatible versions with matching base but different dev suffixes
- Improves error message to say "incompatible" instead of "different"

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: wmayner

pyphi/conf.py

@@ -762,6 +762,15 @@ def always_zero(a, b):
     independent.""",
     )
 
+    VALIDATE_JSON_VERSION = Option(
+        True,
+        type=bool,
+        doc="""
+    Controls whether PyPhi validates that JSON data was saved with a compatible
+    version. If set to ``False``, JSON from any version can be loaded, which
+    may cause errors if the data format changed between versions.""",
+    )
+
     SINGLE_MICRO_NODES_WITH_SELFLOOPS_HAVE_PHI = Option(
         True,
         type=bool,

pyphi/conf.pyi

@@ -84,6 +84,7 @@ class PyphiConfig(Config):
     PROGRESS_BARS: bool
     VALIDATE_SUBSYSTEM_STATES: bool
     VALIDATE_CONDITIONAL_INDEPENDENCE: bool
+    VALIDATE_JSON_VERSION: bool
     SINGLE_MICRO_NODES_WITH_SELFLOOPS_HAVE_PHI: bool
     PRINT_FRACTIONS: bool
     SYSTEM_PARTITION_INCLUDE_COMPLETE: bool

pyphi/jsonify.py

@@ -51,6 +51,21 @@ def from_json(cls, json):
 
 PYPHI_VERSION = get_version("pyphi")
 
+
+def _parse_version(version_str: str) -> tuple[str, str | None]:
+    """Parse version into (base_version, dev_suffix).
+
+    Examples:
+        "2.0.0a1" -> ("2.0.0a1", None)
+        "1.2.1.dev1534+g12345" -> ("1.2.1", "dev1534+g12345")
+    """
+    # Check for .dev suffix pattern (common with hatch-vcs)
+    if ".dev" in version_str:
+        parts = version_str.split(".dev", 1)
+        return parts[0], "dev" + parts[1]
+    return version_str, None
+
+
 # TODO: extend to `macro` objects
 # TODO: resolve schema issues with `vphi` and other external consumers
 # TODO: somehow check schema instead of version?
@@ -251,13 +266,31 @@ def dump(obj, fp, **user_kwargs):
     return json.dump(obj, fp, **_encoder_kwargs(user_kwargs))
 
 
-def _check_version(version):
-    """Check whether the JSON version matches the PyPhi version."""
-    if version != PYPHI_VERSION:
-        raise pyphi.exceptions.JSONVersionError(  # pyright: ignore[reportAttributeAccessIssue]
-            "Cannot load JSON from a different version of PyPhi. "
-            f"JSON version = {version}, current version = {PYPHI_VERSION}."
-        )
+def _check_version(version: str) -> None:
+    """Check whether the JSON version is compatible with current PyPhi version.
+
+    The check can be disabled via config.VALIDATE_JSON_VERSION. When enabled,
+    versions are considered compatible if:
+    1. They match exactly, OR
+    2. Their base versions match (ignoring .dev suffixes from hatch-vcs)
+    """
+    if not pyphi.config.VALIDATE_JSON_VERSION:
+        return
+
+    if version == PYPHI_VERSION:
+        return
+
+    json_base, _ = _parse_version(version)
+    current_base, _ = _parse_version(PYPHI_VERSION)
+
+    if json_base == current_base:
+        # Same base version, just different dev builds
+        return
+
+    raise pyphi.exceptions.JSONVersionError(  # pyright: ignore[reportAttributeAccessIssue]
+        f"Cannot load JSON from incompatible PyPhi version. "
+        f"JSON version = {version}, current version = {PYPHI_VERSION}."
+    )
 
 
 def _is_loadable_model_object(obj):