add new graph param type and common utils to set foundation for structured parameter implementation

Author: CameronBrooks11

CMakeLists.txt

@@ -50,6 +50,7 @@ set(FLUXGRAPH_SOURCES
     src/model/second_order_process.cpp
     src/model/mass_spring_damper.cpp
     src/model/dc_motor.cpp
+    src/graph/param_utils.cpp
     src/graph/compiler.cpp
     src/graph/compiler/algorithms.cpp
     src/graph/compiler/common.cpp

include/fluxgraph/core/types.hpp

@@ -1,7 +1,10 @@
 #pragma once
 
 #include <cstdint>
+#include <map>
 #include <string>
+#include <type_traits>
+#include <vector>
 #include <variant>
 
 namespace fluxgraph {
@@ -69,4 +72,32 @@ struct UnitConversion {
 /// Variant type for command arguments and signal values
 using Variant = std::variant<double, int64_t, bool, std::string>;
 
+class ParamValue;
+
+using ParamArray = std::vector<ParamValue>;
+using ParamObject = std::map<std::string, ParamValue>;
+using ParamScalar = std::variant<double, int64_t, bool, std::string>;
+using ParamVariant =
+    std::variant<double, int64_t, bool, std::string, ParamArray, ParamObject>;
+
+/// Structured parameter value used for graph model/transform parameters.
+/// Command transport continues to use `Variant`.
+class ParamValue : public ParamVariant {
+public:
+  using ParamVariant::ParamVariant;
+  using ParamVariant::operator=;
+
+  ParamValue() : ParamVariant(double{0.0}) {}
+
+  ParamValue(const char *value) : ParamVariant(std::string(value)) {}
+
+  template <typename Integer,
+            typename = std::enable_if_t<std::is_integral_v<Integer> &&
+                                        !std::is_same_v<Integer, bool> &&
+                                        !std::is_same_v<Integer, int64_t>>>
+  ParamValue(Integer value) : ParamVariant(static_cast<int64_t>(value)) {}
+};
+
+using ParamMap = std::map<std::string, ParamValue>;
+
 } // namespace fluxgraph

include/fluxgraph/graph/param_utils.hpp

@@ -0,0 +1,17 @@
+#pragma once
+
+#include "fluxgraph/core/types.hpp"
+#include <string>
+
+namespace fluxgraph::param {
+
+std::string type_name(const ParamValue &value);
+
+double as_double(const ParamValue &value, const std::string &path);
+int64_t as_int64(const ParamValue &value, const std::string &path);
+bool as_bool(const ParamValue &value, const std::string &path);
+std::string as_string(const ParamValue &value, const std::string &path);
+const ParamArray &as_array(const ParamValue &value, const std::string &path);
+const ParamObject &as_object(const ParamValue &value, const std::string &path);
+
+} // namespace fluxgraph::param

include/fluxgraph/graph/spec.hpp

@@ -16,7 +16,7 @@ struct SignalSpec {
 /// POD specification for a transform (protocol-agnostic)
 struct TransformSpec {
   std::string type; // "linear", "first_order_lag", "delay", etc.
-  std::map<std::string, Variant> params;
+  ParamMap params;
 };
 
 /// POD specification for a signal edge in the graph
@@ -30,7 +30,7 @@ struct EdgeSpec {
 struct ModelSpec {
   std::string id;   // e.g., "chamber_air"
   std::string type; // "thermal_mass"
-  std::map<std::string, Variant> params;
+  ParamMap params;
 };
 
 /// POD specification for a rule action

src/graph/compiler/common.cpp

@@ -1,31 +1,14 @@
 #include "common.hpp"
+#include "fluxgraph/graph/param_utils.hpp"
 #include <algorithm>
 #include <cctype>
 #include <cmath>
 #include <stdexcept>
 
 namespace fluxgraph::compiler_internal {
 
-namespace {
-
-std::string variant_type_name(const Variant &value) {
-  if (std::holds_alternative<double>(value)) {
-    return "double";
-  }
-  if (std::holds_alternative<int64_t>(value)) {
-    return "int64";
-  }
-  if (std::holds_alternative<bool>(value)) {
-    return "bool";
-  }
-  return "string";
-}
-
-} // namespace
-
-const Variant &require_param(const std::map<std::string, Variant> &params,
-                             const std::string &name,
-                             const std::string &context) {
+const ParamValue &require_param(const ParamMap &params, const std::string &name,
+                                const std::string &context) {
   auto it = params.find(name);
   if (it == params.end()) {
     throw std::runtime_error("Missing required parameter at " + context + "/" +
@@ -34,31 +17,16 @@ const Variant &require_param(const std::map<std::string, Variant> &params,
   return it->second;
 }
 
-double as_double(const Variant &value, const std::string &path) {
-  if (std::holds_alternative<double>(value)) {
-    return std::get<double>(value);
-  }
-  if (std::holds_alternative<int64_t>(value)) {
-    return static_cast<double>(std::get<int64_t>(value));
-  }
-  throw std::runtime_error("Type error at " + path + ": expected number, got " +
-                           variant_type_name(value));
+double as_double(const ParamValue &value, const std::string &path) {
+  return param::as_double(value, path);
 }
 
-int64_t as_int64(const Variant &value, const std::string &path) {
-  if (std::holds_alternative<int64_t>(value)) {
-    return std::get<int64_t>(value);
-  }
-  throw std::runtime_error("Type error at " + path + ": expected int64, got " +
-                           variant_type_name(value));
+int64_t as_int64(const ParamValue &value, const std::string &path) {
+  return param::as_int64(value, path);
 }
 
-std::string as_string(const Variant &value, const std::string &path) {
-  if (std::holds_alternative<std::string>(value)) {
-    return std::get<std::string>(value);
-  }
-  throw std::runtime_error("Type error at " + path + ": expected string, got " +
-                           variant_type_name(value));
+std::string as_string(const ParamValue &value, const std::string &path) {
+  return param::as_string(value, path);
 }
 
 void require_finite(const double value, const std::string &path) {

src/graph/compiler/common.hpp

@@ -9,13 +9,12 @@
 
 namespace fluxgraph::compiler_internal {
 
-const Variant &require_param(const std::map<std::string, Variant> &params,
-                             const std::string &name,
-                             const std::string &context);
+const ParamValue &require_param(const ParamMap &params, const std::string &name,
+                                const std::string &context);
 
-double as_double(const Variant &value, const std::string &path);
-int64_t as_int64(const Variant &value, const std::string &path);
-std::string as_string(const Variant &value, const std::string &path);
+double as_double(const ParamValue &value, const std::string &path);
+int64_t as_int64(const ParamValue &value, const std::string &path);
+std::string as_string(const ParamValue &value, const std::string &path);
 
 void require_finite(double value, const std::string &path);
 void require_finite_positive(double value, const std::string &path);

src/graph/param_utils.cpp

@@ -0,0 +1,77 @@
+#include "fluxgraph/graph/param_utils.hpp"
+#include <stdexcept>
+
+namespace fluxgraph::param {
+
+std::string type_name(const ParamValue &value) {
+  if (std::holds_alternative<double>(value)) {
+    return "double";
+  }
+  if (std::holds_alternative<int64_t>(value)) {
+    return "int64";
+  }
+  if (std::holds_alternative<bool>(value)) {
+    return "bool";
+  }
+  if (std::holds_alternative<std::string>(value)) {
+    return "string";
+  }
+  if (std::holds_alternative<ParamArray>(value)) {
+    return "array";
+  }
+  return "object";
+}
+
+double as_double(const ParamValue &value, const std::string &path) {
+  if (std::holds_alternative<double>(value)) {
+    return std::get<double>(value);
+  }
+  if (std::holds_alternative<int64_t>(value)) {
+    return static_cast<double>(std::get<int64_t>(value));
+  }
+  throw std::runtime_error("Type error at " + path + ": expected number, got " +
+                           type_name(value));
+}
+
+int64_t as_int64(const ParamValue &value, const std::string &path) {
+  if (std::holds_alternative<int64_t>(value)) {
+    return std::get<int64_t>(value);
+  }
+  throw std::runtime_error("Type error at " + path + ": expected int64, got " +
+                           type_name(value));
+}
+
+bool as_bool(const ParamValue &value, const std::string &path) {
+  if (std::holds_alternative<bool>(value)) {
+    return std::get<bool>(value);
+  }
+  throw std::runtime_error("Type error at " + path + ": expected bool, got " +
+                           type_name(value));
+}
+
+std::string as_string(const ParamValue &value, const std::string &path) {
+  if (std::holds_alternative<std::string>(value)) {
+    return std::get<std::string>(value);
+  }
+  throw std::runtime_error("Type error at " + path + ": expected string, got " +
+                           type_name(value));
+}
+
+const ParamArray &as_array(const ParamValue &value, const std::string &path) {
+  if (std::holds_alternative<ParamArray>(value)) {
+    return std::get<ParamArray>(value);
+  }
+  throw std::runtime_error("Type error at " + path + ": expected array, got " +
+                           type_name(value));
+}
+
+const ParamObject &as_object(const ParamValue &value,
+                             const std::string &path) {
+  if (std::holds_alternative<ParamObject>(value)) {
+    return std::get<ParamObject>(value);
+  }
+  throw std::runtime_error("Type error at " + path + ": expected object, got " +
+                           type_name(value));
+}
+
+} // namespace fluxgraph::param

src/loaders/json_loader.cpp

@@ -11,6 +11,21 @@ namespace fluxgraph::loaders {
 
 namespace {
 
+ParamValue json_to_param_value(const json &j, const std::string &path) {
+  if (j.is_number_float()) {
+    return j.get<double>();
+  } else if (j.is_number_integer()) {
+    return j.get<int64_t>();
+  } else if (j.is_boolean()) {
+    return j.get<bool>();
+  } else if (j.is_string()) {
+    return j.get<std::string>();
+  } else {
+    throw std::runtime_error("JSON parse error at " + path +
+                             ": Unsupported type for Variant");
+  }
+}
+
 // Convert JSON value to Variant
 Variant json_to_variant(const json &j, const std::string &path) {
   if (j.is_number_float()) {
@@ -43,7 +58,7 @@ TransformSpec parse_transform(const json &j, const std::string &base_path) {
   if (j.contains("params") && j["params"].is_object()) {
     for (auto &[key, value] : j["params"].items()) {
       std::string param_path = path + "/params/" + key;
-      spec.params[key] = json_to_variant(value, param_path);
+      spec.params[key] = json_to_param_value(value, param_path);
     }
   }
 
@@ -117,7 +132,7 @@ ModelSpec parse_model(const json &j, const std::string &base_path,
   if (j.contains("params") && j["params"].is_object()) {
     for (auto &[key, value] : j["params"].items()) {
       std::string param_path = path + "/params/" + key;
-      spec.params[key] = json_to_variant(value, param_path);
+      spec.params[key] = json_to_param_value(value, param_path);
     }
   }
 

src/loaders/yaml_loader.cpp

@@ -17,6 +17,31 @@ std::string format_yaml_error(const std::string &message,
          ", column " + std::to_string(mark.column + 1) + ": " + message;
 }
 
+ParamValue yaml_to_param_value(const YAML::Node &node, const std::string &path) {
+  if (node.IsScalar()) {
+    // Try to determine type from the actual content
+    try {
+      // Try boolean first
+      if (node.as<std::string>() == "true" ||
+          node.as<std::string>() == "false") {
+        return node.as<bool>();
+      }
+      // Try integer
+      if (node.as<std::string>().find('.') == std::string::npos) {
+        return node.as<int64_t>();
+      }
+      // Try double
+      return node.as<double>();
+    } catch (...) {
+      // Fall back to string
+      return node.as<std::string>();
+    }
+  } else {
+    throw std::runtime_error("YAML parse error at " + path +
+                             ": Expected scalar value for Variant");
+  }
+}
+
 // Convert YAML node to Variant
 Variant yaml_to_variant(const YAML::Node &node, const std::string &path) {
   if (node.IsScalar()) {
@@ -61,7 +86,7 @@ TransformSpec parse_transform(const YAML::Node &node,
     for (auto it = node["params"].begin(); it != node["params"].end(); ++it) {
       std::string key = it->first.as<std::string>();
       std::string param_path = path + "/params/" + key;
-      spec.params[key] = yaml_to_variant(it->second, param_path);
+      spec.params[key] = yaml_to_param_value(it->second, param_path);
     }
   }
 
@@ -131,7 +156,7 @@ ModelSpec parse_model(const YAML::Node &node, size_t index) {
     for (auto it = node["params"].begin(); it != node["params"].end(); ++it) {
       std::string key = it->first.as<std::string>();
       std::string param_path = path + "/params/" + key;
-      spec.params[key] = yaml_to_variant(it->second, param_path);
+      spec.params[key] = yaml_to_param_value(it->second, param_path);
     }
   }
 

tests/integration/determinism_test.cpp

@@ -26,7 +26,7 @@ class DeterministicCustomTransform : public ITransform {
   double gain_ = 1.0;
 };
 
-double variant_to_double(const Variant &value) {
+double variant_to_double(const ParamValue &value) {
   if (std::holds_alternative<double>(value)) {
     return std::get<double>(value);
   }