Add exploy version to metadata and validate (#52)

# Pull Request

### What change is being made

Add the exploy version to the metadata of the ONNX file and validate
against supported range in controller.

### Why this change is being made

Better handling of version changes.

### Tested

Confirmed version is present and tests are passing.

GitOrigin-RevId: f67c1a80dff003665a5119aaa1cdae3849865b9d

Author: awoll-bdai

control/CMakeLists.txt

@@ -53,6 +53,7 @@ add_executable(exploy_test
     test/components_test.cpp
     test/context_test.cpp
     test/logging_test.cpp
+    test/metadata_test.cpp
     test/onnx_runtime_test.cpp
     "${GEN_OUTPUT}"
 )

control/context.cpp

@@ -50,6 +50,8 @@ bool OnnxContext::createContext(OnnxRuntime& onnx_model, bool strict) {
     return false;
   }
 
+  if (!metadata::checkExployVersion(onnx_model.getCustomMetadata("exploy_version"))) return false;
+
   std::optional<int> maybe_update_rate = parseUpdateRate(onnx_model);
   if (!maybe_update_rate.has_value()) return false;
   update_rate_ = maybe_update_rate.value();

control/metadata.hpp

@@ -5,6 +5,7 @@
 #include <nlohmann/json.hpp>
 
 #include <optional>
+#include <regex>
 #include <string>
 #include <vector>
 
@@ -249,4 +250,78 @@ inline void from_json(const json& j, JointMetadata& jm) {
   j.at("joint_names").get_to(jm.names);
 }
 
+/**
+ * @brief Parsed semantic version (MAJOR.MINOR.PATCH).
+ */
+struct Version {
+  int major{0};
+  int minor{0};
+  int patch{0};
+
+  std::string toString() const { return fmt::format("{}.{}.{}", major, minor, patch); }
+
+  bool operator<=(const Version& other) const {
+    if (major != other.major) return major < other.major;
+    if (minor != other.minor) return minor < other.minor;
+    return patch <= other.patch;
+  }
+};
+
+constexpr Version kMinSupportedExployVersion{0, 1, 0};
+constexpr Version kMaxSupportedExployVersion{0, 1, 0};
+
+/**
+ * @brief Parse a "MAJOR.MINOR.PATCH" version string.
+ *
+ * @param s Version string to parse.
+ * @return Parsed Version, or std::nullopt if the string is not a valid semver.
+ */
+inline std::optional<Version> parseVersion(const std::string& s) {
+  static const std::regex kVersionRegex(R"(^(\d+)\.(\d+)\.(\d+)$)");
+  std::smatch match;
+  if (!std::regex_match(s, match, kVersionRegex)) return std::nullopt;
+  return Version{std::stoi(match[1]), std::stoi(match[2]), std::stoi(match[3])};
+}
+
+/**
+ * @brief Check that the ONNX model's exploy_version metadata is present and within the supported
+ * range [kMinSupportedExployVersion, kMaxSupportedExployVersion]. Logs an error if not.
+ *
+ * @param maybe_version_str The value of the "exploy_version" metadata key, or std::nullopt if
+ * absent.
+ * @return true if the version is present and within the supported range, false otherwise.
+ */
+inline bool checkExployVersion(const std::optional<std::string>& maybe_version_str) {
+  if (!maybe_version_str.has_value()) {
+    LOG(ERROR,
+        "ONNX model does not contain 'exploy_version' metadata. The ONNX file is not "
+        "compatible with this controller.");
+    return false;
+  }
+
+  std::string version_str;
+  try {
+    version_str = json::parse(maybe_version_str.value()).get<std::string>();
+  } catch (const json::exception&) {
+    LOG_STREAM(ERROR, "Failed to parse exploy_version: '" << maybe_version_str.value() << "'.");
+    return false;
+  }
+
+  auto maybe_version = parseVersion(version_str);
+  if (!maybe_version.has_value()) {
+    LOG_STREAM(ERROR, "Failed to parse exploy_version: '" << version_str << "'.");
+    return false;
+  }
+
+  const auto& v = maybe_version.value();
+  const bool in_range = kMinSupportedExployVersion <= v && v <= kMaxSupportedExployVersion;
+  if (!in_range) {
+    LOG_STREAM(ERROR, "exploy_version '" << version_str << "' is outside the supported range ["
+                                         << kMinSupportedExployVersion.toString() << ", "
+                                         << kMaxSupportedExployVersion.toString() << "].");
+    return false;
+  }
+  return true;
+}
+
 }  // namespace exploy::control::metadata

control/test/metadata_test.cpp

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Robotics and AI Institute LLC dba RAI Institute. All rights reserved.
+
+#include "metadata.hpp"
+
+#include <gtest/gtest.h>
+
+namespace exploy::control::metadata {
+
+// ========== Version::toString ==========
+
+TEST(VersionTest, ToString) {
+  EXPECT_EQ((Version{1, 2, 3}.toString()), "1.2.3");
+  EXPECT_EQ((Version{0, 0, 0}.toString()), "0.0.0");
+  EXPECT_EQ((Version{10, 20, 30}.toString()), "10.20.30");
+}
+
+// ========== Version::operator<= ==========
+
+TEST(VersionTest, ComparisonEqualVersions) {
+  EXPECT_TRUE((Version{1, 2, 3} <= Version{1, 2, 3}));
+  EXPECT_TRUE((Version{0, 0, 0} <= Version{0, 0, 0}));
+}
+
+TEST(VersionTest, ComparisonMajorDiffers) {
+  EXPECT_TRUE((Version{0, 9, 9} <= Version{1, 0, 0}));
+  EXPECT_FALSE((Version{2, 0, 0} <= Version{1, 9, 9}));
+}
+
+TEST(VersionTest, ComparisonMinorDiffers) {
+  EXPECT_TRUE((Version{1, 1, 9} <= Version{1, 2, 0}));
+  EXPECT_FALSE((Version{1, 3, 0} <= Version{1, 2, 9}));
+}
+
+TEST(VersionTest, ComparisonPatchDiffers) {
+  EXPECT_TRUE((Version{1, 2, 2} <= Version{1, 2, 3}));
+  EXPECT_FALSE((Version{1, 2, 4} <= Version{1, 2, 3}));
+}
+
+// ========== parseVersion ==========
+
+TEST(ParseVersionTest, ValidVersion) {
+  auto v = parseVersion("1.2.3");
+  ASSERT_TRUE(v.has_value());
+  EXPECT_EQ(v->major, 1);
+  EXPECT_EQ(v->minor, 2);
+  EXPECT_EQ(v->patch, 3);
+}
+
+TEST(ParseVersionTest, ZeroVersion) {
+  auto v = parseVersion("0.0.0");
+  ASSERT_TRUE(v.has_value());
+  EXPECT_EQ(v->major, 0);
+  EXPECT_EQ(v->minor, 0);
+  EXPECT_EQ(v->patch, 0);
+}
+
+TEST(ParseVersionTest, LargeNumbers) {
+  auto v = parseVersion("10.20.30");
+  ASSERT_TRUE(v.has_value());
+  EXPECT_EQ(v->major, 10);
+  EXPECT_EQ(v->minor, 20);
+  EXPECT_EQ(v->patch, 30);
+}
+
+TEST(ParseVersionTest, EmptyString) {
+  EXPECT_FALSE(parseVersion("").has_value());
+}
+
+TEST(ParseVersionTest, MissingPatch) {
+  EXPECT_FALSE(parseVersion("1.2").has_value());
+}
+
+TEST(ParseVersionTest, ExtraComponent) {
+  EXPECT_FALSE(parseVersion("1.2.3.4").has_value());
+}
+
+TEST(ParseVersionTest, NonNumericComponents) {
+  EXPECT_FALSE(parseVersion("a.b.c").has_value());
+}
+
+TEST(ParseVersionTest, NegativeComponent) {
+  EXPECT_FALSE(parseVersion("1.2.-3").has_value());
+}
+
+TEST(ParseVersionTest, WithVPrefix) {
+  EXPECT_FALSE(parseVersion("v1.2.3").has_value());
+}
+
+// ========== checkExployVersion ==========
+
+TEST(CheckExployVersionTest, MissingMetadata) {
+  EXPECT_FALSE(checkExployVersion(std::nullopt));
+}
+
+TEST(CheckExployVersionTest, InvalidJson) {
+  EXPECT_FALSE(checkExployVersion("not_valid_json"));
+}
+
+TEST(CheckExployVersionTest, JsonNotAString) {
+  // JSON-encoded number instead of a string
+  EXPECT_FALSE(checkExployVersion("42"));
+}
+
+TEST(CheckExployVersionTest, InvalidSemver) {
+  // JSON-encoded string that is not a valid semver
+  EXPECT_FALSE(checkExployVersion("\"abc\""));
+}
+
+TEST(CheckExployVersionTest, VersionBelowMinimum) {
+  // kMinSupportedExployVersion is 0.1.0, so 0.0.9 is below the minimum
+  EXPECT_FALSE(checkExployVersion("\"0.0.9\""));
+}
+
+TEST(CheckExployVersionTest, VersionAboveMaximum) {
+  // kMaxSupportedExployVersion is 0.1.0, so 0.2.0 is above the maximum
+  EXPECT_FALSE(checkExployVersion("\"0.2.0\""));
+}
+
+TEST(CheckExployVersionTest, SupportedVersion) {
+  // kMinSupportedExployVersion == kMaxSupportedExployVersion == 0.1.0
+  EXPECT_TRUE(checkExployVersion("\"0.1.0\""));
+}
+
+}  // namespace exploy::control::metadata

control/test/testdata/test_onnx_generator.py

@@ -214,6 +214,7 @@ def get_articulation_metadata() -> dict:
 def get_env_metadata() -> dict:
     """Returns metadata for environment configuration."""
     return {
+        "exploy_version": "0.1.0",
         "update_rate": 10.0,
     }
 

exploy/exporter/core/exporter.py

@@ -11,7 +11,7 @@
 
 from exploy.exporter.core.exportable_environment import ExportableEnvironment
 from exploy.exporter.core.utils.onnx import construct_decimation_wrapper
-from exploy.exporter.core.utils.paths import prepare_onnx_paths
+from exploy.exporter.core.utils.paths import get_exploy_version, prepare_onnx_paths
 
 
 def export_environment_as_onnx(
@@ -239,6 +239,8 @@ def export(
         wrapper_model = construct_decimation_wrapper(
             model_a=onnx.load(str(export_paths.get_debug_path("default"))),
             model_b=onnx.load(str(export_paths.get_debug_path("process_actions"))),
+            name_a="default",
+            name_b="process_actions",
             decimation=self._env.decimation,
             opset_version=self._opset_version,
             ir_version=self._ir_version,
@@ -258,6 +260,11 @@ def export(
         meta.key = "date_exported (YYMMDD.HHMMSS)"
         meta.value = str(datetime.datetime.now().strftime("%y%m%d.%H%M%S"))
 
+        # Exploy version.
+        meta = onnx_model.metadata_props.add()
+        meta.key = "exploy_version"
+        meta.value = json.dumps(get_exploy_version())
+
         # Environment metadata.
         for key, value in self._env.metadata().items():
             meta = onnx_model.metadata_props.add()

exploy/exporter/core/utils/onnx.py

@@ -21,6 +21,8 @@ def _copy_value_info(value_info: onnx.ValueInfoProto) -> onnx.ValueInfoProto:
 def construct_decimation_wrapper(
     model_a: onnx.ModelProto,
     model_b: onnx.ModelProto,
+    name_a: str,
+    name_b: str,
     decimation: int,
     opset_version: int,
     ir_version: int,
@@ -30,7 +32,11 @@ def construct_decimation_wrapper(
     Args:
         model_a: ONNX submodel for decimation event.
         model_b: ONNX submodel for other steps.
+        name_a: Name for model_a graph.
+        name_b: Name for model_b graph.
         decimation: Decimation factor.
+        opset_version: ONNX opset version to use.
+        ir_version: ONNX IR version to use.
     Returns:
         An ONNX ModelProto with fixed periodic conditional branching.
     """
@@ -51,6 +57,9 @@ def construct_decimation_wrapper(
     mod_node = onnx.helper.make_node("Mod", ["ctx.step_count", "decimation"], ["is_event"])
     eq_node = onnx.helper.make_node("Equal", ["is_event", "zero"], ["cond"])
 
+    model_a.graph.name = name_a
+    model_b.graph.name = name_b
+
     # Remove submodel inputs (will be passed by parent graph)
     for g in (model_a.graph, model_b.graph):
         del g.input[:]

exploy/exporter/core/utils/paths.py

@@ -1,5 +1,6 @@
 # Copyright (c) 2026 Robotics and AI Institute LLC dba RAI Institute. All rights reserved.
 
+import importlib.metadata
 import pathlib
 from dataclasses import dataclass
 
@@ -16,6 +17,18 @@
 ONNX_EXTENSION = ".onnx"
 
 
+def get_exploy_version() -> str:
+    """Get the installed exploy-exporter-core package version.
+
+    Returns:
+        Version string, or "unknown" if the package metadata is not available.
+    """
+    try:
+        return importlib.metadata.version("exploy-exporter-core")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
 def _ensure_onnx_extension(filename: str) -> pathlib.Path:
     """Ensure filename has .onnx extension.