refactor: Phase 3 — JSON serializer, IO alignment, sanitization, operator>> decomposition

CMakeLists.txt

@@ -545,6 +545,8 @@ set(LIBHMM_SOURCES
     src/training/viterbi_trainer.cpp
     src/training/segmental_kmeans_trainer.cpp
     src/io/file_io_manager.cpp
+    src/io/json_utils.cpp
+    src/io/hmm_json.cpp
     src/io/xml_file_reader.cpp
     src/io/xml_file_writer.cpp
 )

examples/basic_hmm_example.cpp

@@ -5,10 +5,9 @@
  *    Demonstrates ForwardBackward probability evaluation.
  * 2. Distribution showcase — PDF evaluation and MLE fitting.
  * 3. Viterbi training on a 3-state Gaussian HMM.
- * 4. XML file round-trip.
+ * 4. JSON file round-trip (save_json / load_json).
  */
 #include <iostream>
-#include <fstream>
 #include <memory>
 #include <vector>
 #include <cmath>
@@ -181,7 +180,11 @@ int main() {
         std::cout << hmm << std::endl;
     }
     {
-        std::cout << "Testing File Read/Write" << std::endl;
+        // =====================================================================
+        // 4. JSON file round-trip
+        // =====================================================================
+        std::cout << "Testing JSON File Round-Trip" << std::endl;
+        std::cout << "---------------------------" << std::endl;
         Hmm hmm(2);
         Vector pi(2);
         Matrix trans(2, 2);
@@ -196,17 +199,18 @@ int main() {
         hmm.setTrans(trans);
         hmm.setDistribution(0, std::make_unique<GaussianDistribution>());
         hmm.setDistribution(1, std::make_unique<GaussianDistribution>(2.0, 2.0));
-        std::ofstream of("testrw", std::ios::out);
 
-        std::cout << hmm << std::endl;
-        of << hmm << std::endl;
-        of.close();
+        std::cout << "Original HMM:\n" << hmm << std::endl;
+
+        // Save to JSON — exact round-trip at max_digits10 precision.
+        const std::filesystem::path jsonPath = "basic_hmm.json";
+        libhmm::save_json(hmm, jsonPath);
+        std::cout << "Saved to: " << jsonPath << std::endl;
 
-        Hmm hmm1(2);
-        std::ifstream inf("testrw", std::ios::in);
-        inf >> hmm1;
-        //        inf.close( );
+        // Load back.
+        Hmm loaded = libhmm::load_json(jsonPath);
+        std::cout << "Loaded HMM:\n" << loaded << std::endl;
 
-        std::cout << hmm1 << std::endl;
+        std::filesystem::remove(jsonPath); // clean up
     }
 }

include/libhmm/common/common.h

@@ -1,11 +1,8 @@
 #pragma once
 
 // Core C++ standard library headers used throughout the library.
-// Lean version: linalg types (Matrix, Vector, ObservationSet, etc.) and XML
-// serialization helpers now live in separate headers:
-//   libhmm/linalg/linalg_types.h  — type aliases and clear_* helpers
-//   libhmm/common/serialization.h — MatrixSerializer / VectorSerializer
-// Include those headers from files that need them.
+// Linalg types (Matrix, Vector, ObservationSet, etc.) live in
+// libhmm/linalg/linalg_types.h — include that from files that need them.
 
 #include <vector>
 #include <memory>

include/libhmm/distributions/beta_distribution.h

@@ -166,6 +166,9 @@ class BetaDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the alpha (α) shape parameter.

include/libhmm/distributions/binomial_distribution.h

@@ -92,6 +92,9 @@ class BinomialDistribution : public DistributionBase {
 
     void reset() noexcept override;
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     [[nodiscard]] int getN() const noexcept { return n_; }
     [[nodiscard]] double getP() const noexcept { return p_; }

include/libhmm/distributions/chi_squared_distribution.h

@@ -115,6 +115,9 @@ class ChiSquaredDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the degrees of freedom parameter.

include/libhmm/distributions/discrete_distribution.h

@@ -189,9 +189,12 @@ class DiscreteDistribution : public DistributionBase {
      * @return String showing all symbol probabilities
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
-     * Gets the number of discrete symbols in the distribution.
+     * Gets the number of discrete symbols
      *
      * @return Number of symbols/categories
      */

include/libhmm/distributions/distribution_base.h

@@ -7,6 +7,12 @@
 
 namespace libhmm {
 
+// Forward declaration — concrete distributions declare from_json(json::Reader&)
+// as a static factory method; implementation is in src/io/hmm_json.cpp.
+namespace json {
+class Reader;
+} // namespace json
+
 /**
  * @brief Shared implementation base for all emission distributions.
  *

include/libhmm/distributions/emission_distribution.h

@@ -92,7 +92,17 @@ class EmissionDistribution {
     // Metadata
     // =========================================================================
 
-    [[nodiscard]] virtual std::string toString() const = 0;
+    /** @brief Human-readable string representation.  Delegates to to_json(). */
+    [[nodiscard]] virtual std::string toString() const { return to_json(); }
+
+    /**
+     * @brief Serialise to a compact JSON object string.
+     *
+     * Must produce output that round-trips exactly through the matching
+     * static from_json() factory registered in src/io/hmm_json.cpp.
+     * Use json::write_distribution() from libhmm/io/json_utils.h.
+     */
+    [[nodiscard]] virtual std::string to_json() const = 0;
 
     /** @brief Returns true for discrete (PMF) distributions, false for continuous (PDF). */
     [[nodiscard]] virtual bool isDiscrete() const noexcept = 0;

include/libhmm/distributions/exponential_distribution.h

@@ -134,6 +134,9 @@ class ExponentialDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the rate parameter λ.

include/libhmm/distributions/gamma_distribution.h

@@ -168,6 +168,9 @@ class GammaDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     [[nodiscard]] std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the shape parameter k.

include/libhmm/distributions/gaussian_distribution.h

@@ -157,6 +157,9 @@ class GaussianDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the mean parameter μ.

include/libhmm/distributions/log_normal_distribution.h

@@ -131,6 +131,9 @@ class LogNormalDistribution : public DistributionBase {
      * @return String describing the distribution parameters
      */
     std::string toString() const override;
+    [[nodiscard]] std::string to_json() const override;
+    /// @internal JSON factory — called by the distribution registry in src/io/hmm_json.cpp.
+    static std::unique_ptr<EmissionDistribution> from_json(json::Reader &r);
 
     /**
      * Gets the mean parameter μ of the underlying normal distribution.