logging updates

tooling/pipeline/includes/biergarten_pipeline_orchestrator.h

@@ -1,8 +1,8 @@
-#ifndef BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
-#define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_PIPELINE_ORCHESTRATOR_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_PIPELINE_ORCHESTRATOR_H_
 
 /**
- * @file biergarten_data_generator.h
+ * @file biergarten_pipeline_orchestrator.h
  * @brief Orchestration for end-to-end brewery data generation pipeline.
  *
  * Intent: Coordinates location loading, enrichment, and generation phases
@@ -28,14 +28,14 @@
  */
 class BiergartenPipelineOrchestrator {
  public:
-/**
- * @brief Constructs the orchestrator with injected pipeline dependencies.
- *
- * @param context_service Provides regional context for locations.
- * @param generator Implementation (Llama or Mock) for brewery/user generation.
- * @param exporter Database backend for persisting generated records.
- * @param application_options CLI configuration and paths.
- */
+  /**
+   * @brief Constructs the orchestrator with injected pipeline dependencies.
+   *
+   * @param context_service Provides regional context for locations.
+   * @param generator Implementation (Llama or Mock) for brewery/user generation.
+   * @param exporter Database backend for persisting generated records.
+   * @param application_options CLI configuration and paths.
+   */
   BiergartenPipelineOrchestrator(
       std::shared_ptr<ILogger> logger,
       std::unique_ptr<IEnrichmentService> context_service,
@@ -65,11 +65,11 @@ class BiergartenPipelineOrchestrator {
   /// @brief Generator dependency selected in the composition root.
   std::unique_ptr<DataGenerator> generator_;
 
-   /// @brief Storage backend for generated brewery records.
-   std::unique_ptr<IExportService> exporter_;
+  /// @brief Storage backend for generated brewery records.
+  std::unique_ptr<IExportService> exporter_;
 
-   /// @brief CLI configuration: paths, model settings, generation parameters.
-   ApplicationOptions application_options_;
+  /// @brief CLI configuration: paths, model settings, generation parameters.
+  ApplicationOptions application_options_;
 
   /**
    * @brief Load locations from JSON and sample cities.
@@ -93,4 +93,5 @@ class BiergartenPipelineOrchestrator {
   /// @brief Stores generated brewery data.
   std::vector<GeneratedBrewery> generated_breweries_;
 };
-#endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_DATA_GENERATOR_H_
+
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_BIERGARTEN_PIPELINE_ORCHESTRATOR_H_

tooling/pipeline/includes/concurrency/bounded_channel.h

@@ -8,7 +8,7 @@
 #include <queue>
 
 /**
- * @file bounded_channel.h
+ * @file concurrency/bounded_channel.h
  * @brief Thread-safe, bounded multi-producer/multi-consumer synchronous channel.
  *
  * Intent: Enables asynchronous inter-thread communication with backpressure.

tooling/pipeline/includes/data_generation/prompt_formatting/gemma4_jinja_prompt_formatter.h

@@ -1,6 +1,11 @@
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_PROMPT_FORMATTING_GEMMA4_JINJA_PROMPT_FORMATTER_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_PROMPT_FORMATTING_GEMMA4_JINJA_PROMPT_FORMATTER_H_
 
+/**
+ * @file data_generation/prompt_formatting/gemma4_jinja_prompt_formatter.h
+ * @brief Prompt formatter for Google Gemma 4 model using Jinja2 template syntax.
+ */
+
 #include <string>
 #include <string_view>
 

tooling/pipeline/includes/data_generation/prompt_formatting/prompt_formatter.h

@@ -1,6 +1,11 @@
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_PROMPT_FORMATTING_PROMPT_FORMATTER_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_DATA_GENERATION_PROMPT_FORMATTING_PROMPT_FORMATTER_H_
 
+/**
+ * @file data_generation/prompt_formatting/prompt_formatter.h
+ * @brief Abstract interface for formatting system and user prompts.
+ */
+
 #include <string>
 #include <string_view>
 

tooling/pipeline/includes/json_handling/pretty_print.h

@@ -0,0 +1,109 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_PRETTY_PRINT_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_JSON_HANDLING_PRETTY_PRINT_H_
+
+/**
+ * @file json_handling/pretty_print.h
+ * @brief Pretty-printing utilities for JSON values.
+ *
+ * Provides formatting capability for boost::json::value with indentation and
+ * readable output. Adapted from Boost JSON library examples.
+ */
+
+#include <boost/json.hpp>
+#include <ostream>
+#include <string>
+
+/**
+ * @brief Pretty-prints a JSON value to an output stream with indentation.
+ *
+ * Recursively formats JSON objects and arrays with consistent 4-space
+ * indentation. Adapted from:
+ * https://raw.githubusercontent.com/boostorg/json/refs/heads/develop/example/pretty.cpp
+ *
+ * @param outstream Output stream to write formatted JSON.
+ * @param json_val JSON value to format.
+ * @param indent Optional indentation string (managed internally on first call).
+ */
+inline void PrettyPrint(std::ostream& outstream,
+                        boost::json::value const& json_val,
+                        std::string* indent = nullptr) {
+  std::string str;
+  if (indent == nullptr) {
+    indent = &str;
+  }
+  switch (json_val.kind()) {
+    case boost::json::kind::object: {
+      outstream << "{\n";
+      indent->append(4, ' ');
+      auto const& obj = json_val.get_object();
+      if (!obj.empty()) {
+        const auto* iter = obj.begin();
+        for (;;) {
+          outstream << *indent << boost::json::serialize(iter->key()) << " : ";
+          PrettyPrint(outstream, iter->value(), indent);
+          iter = std::next(iter);
+          if (iter == obj.end()) {
+            break;
+          }
+
+          outstream << ",\n";
+        }
+      }
+      outstream << "\n";
+      indent->resize(indent->size() - 4);
+      outstream << *indent << "}";
+      break;
+    }
+
+    case boost::json::kind::array: {
+      outstream << "[\n";
+      indent->append(4, ' ');
+      auto const& arr = json_val.get_array();
+      if (!arr.empty()) {
+        const auto* iter = arr.begin();
+        for (;;) {
+          outstream << *indent;
+          PrettyPrint(outstream, *iter, indent);
+          iter = std::next(iter);
+          if (iter == arr.end()) {
+            break;
+          }
+          outstream << ",\n";
+        }
+      }
+      outstream << "\n";
+      indent->resize(indent->size() - 4);
+      outstream << *indent << "]";
+      break;
+    }
+
+    case boost::json::kind::string: {
+      outstream << serialize(json_val.get_string());
+      break;
+    }
+
+    case boost::json::kind::uint64:
+    case boost::json::kind::int64:
+    case boost::json::kind::double_:
+      outstream << json_val;
+      break;
+
+    case boost::json::kind::bool_:
+      if (json_val.get_bool()) {
+        outstream << "true";
+      } else {
+        outstream << "false";
+      }
+      break;
+
+    case boost::json::kind::null:
+      outstream << "null";
+      break;
+  }
+
+  if (indent->empty()) {
+    outstream << "\n";
+  }
+}
+
+#endif

tooling/pipeline/includes/services/database/export_service.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_DATABASE_EXPORT_SERVICE_H_
 
 /**
- * @file services/export_service.h
+ * @file services/database/export_service.h
  * @brief Abstraction for persisting generated brewery data.
  */
 

tooling/pipeline/includes/services/database/sqlite_connection_helpers.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_DATABASE_SQLITE_CONNECTION_HELPERS_H_
 
 /**
- * @file services/sqlite_connection_helpers.h
+ * @file services/database/sqlite_connection_helpers.h
  * @brief Declarations for connection-level SQLite helper functions.
  */
 

tooling/pipeline/includes/services/database/sqlite_export_service.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_DATABASE_SQLITE_EXPORT_SERVICE_H_
 
 /**
- * @file services/sqlite_export_service.h
+ * @file services/database/sqlite_export_service.h
  * @brief SQLite-backed export service for generated brewery data.
  */
 

tooling/pipeline/includes/services/database/sqlite_statement_helpers.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_DATABASE_SQLITE_STATEMENT_HELPERS_H_
 
 /**
- * @file services/sqlite_statement_helpers.h
+ * @file services/database/sqlite_statement_helpers.h
  * @brief Declarations for statement-level SQLite helper functions and
  * constants.
  */

tooling/pipeline/includes/services/datetime/date_time_provider.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_DATETIME_DATE_TIME_PROVIDER_H_
 
 /**
- * @file services/date_time_provider.h
+ * @file services/datetime/date_time_provider.h
  * @brief Abstraction for UTC timestamp generation.
  */
 

tooling/pipeline/includes/services/datetime/timer.h

@@ -4,7 +4,7 @@
 #include <chrono>
 
 /**
- * @file services/timer.h
+ * @file services/datetime/timer.h
  * @brief Simple timer utility for measuring elapsed time.
  */
 class Timer {

tooling/pipeline/includes/services/enrichment/enrichment_service.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_ENRICHMENT_SERVICE_H_
 
 /**
- * @file services/enrichment_service.h
+ * @file services/enrichment/enrichment_service.h
  * @brief Abstraction for resolving contextual enrichment for a location.
  */
 

tooling/pipeline/includes/services/enrichment/mock_enrichment.h

@@ -1,15 +1,29 @@
-//
-// Created by aaronpo on 13/05/2026.
-//
-
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_MOCK_ENRICHMENT_H_
+
+/**
+ * @file services/enrichment/mock_enrichment.h
+ * @brief Mock implementation of enrichment service for testing.
+ */
+
 #include <string>
 
 #include "enrichment_service.h"
 
+/**
+ * @brief Mock implementation of enrichment service for testing and prototyping.
+ *
+ * Returns empty context without performing actual web queries or enrichment.
+ * Useful for unit tests and development scenarios.
+ */
 class MockEnrichmentService final : public IEnrichmentService {
  public:
+  /**
+   * @brief Returns empty location context.
+   *
+   * @param loc Unused location parameter.
+   * @return Empty string (no enrichment performed).
+   */
   std::string GetLocationContext(const Location& /*loc*/) override {
     return {};
   }

tooling/pipeline/includes/services/enrichment/wikipedia_service.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_ENRICHMENT_WIKIPEDIA_SERVICE_H_
 
 /**
- * @file services/wikipedia_service.h
+ * @file services/enrichment/wikipedia_service.h
  * @brief Wikipedia summary retrieval service with in-memory caching.
  */
 

tooling/pipeline/includes/services/logging/log_dispatcher.h

@@ -6,8 +6,8 @@
  * them to spdlog on a dedicated thread.
  */
 
-#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_
-#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_DISPATCHER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_DISPATCHER_H_
 
 #include <spdlog/spdlog.h>
 
@@ -23,31 +23,31 @@
  */
 class LogDispatcher {
  public:
-   /**
-     * @brief Construct a log dispatcher.
-    *
-     * @param channel Reference to the bounded channel used for log retrieval.
-    */
-   explicit LogDispatcher(BoundedChannel<LogEntry>& channel);
+  /**
+   * @brief Construct a log dispatcher.
+   *
+   * @param channel Reference to the bounded channel used for log retrieval.
+   */
+  explicit LogDispatcher(BoundedChannel<LogEntry>& channel);
 
-   LogDispatcher(const LogDispatcher&) = delete;
-   LogDispatcher& operator=(const LogDispatcher&) = delete;
-   LogDispatcher(LogDispatcher&&) = delete;
-   LogDispatcher& operator=(LogDispatcher&&) = delete;
-   ~LogDispatcher() = default;
+  LogDispatcher(const LogDispatcher&) = delete;
+  LogDispatcher& operator=(const LogDispatcher&) = delete;
+  LogDispatcher(LogDispatcher&&) = delete;
+  LogDispatcher& operator=(LogDispatcher&&) = delete;
+  ~LogDispatcher() = default;
 
-   /**
-     * @brief Drain the channel and forward entries to spdlog.
-    *
-     * Intended to be called once on a dedicated thread. The loop returns after
-     * the channel has been closed and all queued entries have been processed.
-    */
-   void Run();
+  /**
+   * @brief Drain the channel and forward entries to spdlog.
+   *
+   * Intended to be called once on a dedicated thread. The loop returns after
+   * the channel has been closed and all queued entries have been processed.
+   */
+  void Run();
 
  private:
-   BoundedChannel<LogEntry>& channel_;
+  BoundedChannel<LogEntry>& channel_;
 
-   static spdlog::level::level_enum ToSpdlogLevel(LogLevel level);
+  static spdlog::level::level_enum ToSpdlogLevel(LogLevel level);
 };
 
-#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_CONSUMER_H_
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_DISPATCHER_H_

tooling/pipeline/includes/services/logging/log_entry.h

@@ -1,3 +1,6 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
+
 /**
  * @file services/logging/log_entry.h
  * @brief Structured log record shared by the pipeline logging infra.
@@ -6,8 +9,6 @@
  * logging producer and dispatcher through BoundedChannel<LogEntry>.
  */
 
-#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
-#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_ENTRY_H_
 
 #include <chrono>
 #include <thread>

tooling/pipeline/includes/services/logging/log_producer.h

@@ -6,8 +6,8 @@
  * a bounded channel for later processing by the dispatcher.
  */
 
-#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_
-#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_PRODUCER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_PRODUCER_H_
 
 #include <string_view>
 
@@ -24,30 +24,29 @@
  */
 class LogProducer final : public ILogger {
  public:
-   /**
-     * @brief Construct a channel-backed producer.
-    *
-     * @param channel Reference to the bounded channel used for log transfer.
-    */
-   explicit LogProducer(BoundedChannel<LogEntry>& channel);
+  /**
+   * @brief Construct a channel-backed producer.
+   *
+   * @param channel Reference to the bounded channel used for log transfer.
+   */
+  explicit LogProducer(BoundedChannel<LogEntry>& channel);
 
-   LogProducer(const LogProducer&) = delete;
-   LogProducer& operator=(const LogProducer&) = delete;
-   LogProducer(LogProducer&&) = delete;
-   LogProducer& operator=(LogProducer&&) = delete;
+  LogProducer(const LogProducer&) = delete;
+  LogProducer& operator=(const LogProducer&) = delete;
+  LogProducer(LogProducer&&) = delete;
+  LogProducer& operator=(LogProducer&&) = delete;
 
-   ~LogProducer() override = default;
+  ~LogProducer() override = default;
 
-   /**
-     * @brief Queue a log message for asynchronous processing.
-    *
-     * Blocks while the channel applies backpressure.
-    */
-   void Log(LogLevel level, PipelinePhase phase,
-            std::string_view message) override;
+  /**
+   * @brief Queue a log message for asynchronous processing.
+   *
+   * Blocks while the channel applies backpressure.
+   */
+  void Log(LogEntry const& entry) override;
 
  private:
-   BoundedChannel<LogEntry>& channel_;
+  BoundedChannel<LogEntry>& channel_;
 };
 
-#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_CHANNEL_LOGGER_H_
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOG_PRODUCER_H_

tooling/pipeline/includes/services/logging/logger.h

@@ -1,3 +1,6 @@
+#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
+#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
+
 /**
  * @file services/logging/logger.h
  * @brief Abstract logging interface used by pipeline components.
@@ -6,8 +9,6 @@
  * transport, buffering, and formatting implementation.
  */
 
-#ifndef BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
-#define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_
 
 #include <optional>
 #include <string>
@@ -24,22 +25,20 @@
  */
 class ILogger {
  public:
-   ILogger() = default;
-   ILogger(const ILogger&) = delete;
-   ILogger& operator=(const ILogger&) = delete;
-   ILogger(ILogger&&) = delete;
-   ILogger& operator=(ILogger&&) = delete;
-   virtual ~ILogger() = default;
+  ILogger() = default;
+  ILogger(const ILogger&) = delete;
+  ILogger& operator=(const ILogger&) = delete;
+  ILogger(ILogger&&) = delete;
+  ILogger& operator=(ILogger&&) = delete;
+  virtual ~ILogger() = default;
 
-   /**
-     * @brief Submit a log message to the logging subsystem.
-    *
-     * @param level Severity of the message.
-     * @param phase Pipeline execution phase associated with the message.
-     * @param message Log message text.
-    */
-   virtual void Log(LogLevel level, PipelinePhase phase,
-                    std::string_view message) = 0;
+  /**
+   * @brief Submit a log message to the logging subsystem.
+   *
+   * @param entry Structured log record containing message and metadata.
+   *
+   */
+  virtual void Log(const LogEntry& entry) = 0;
 };
 
 #endif  // BIERGARTEN_PIPELINE_INCLUDES_SERVICES_LOGGING_LOGGER_H_

tooling/pipeline/includes/services/prompting/prompt_directory.h

@@ -2,7 +2,7 @@
 #define BIERGARTEN_PIPELINE_INCLUDES_SERVICES_PROMPTING_PROMPT_DIRECTORY_H_
 
 /**
- * @file services/prompt_directory.h
+ * @file services/prompting/prompt_directory.h
  * @brief Interface and filesystem-backed implementation for named prompt
  * loading.
  *

tooling/pipeline/includes/web_client/http_web_client.h

@@ -1,19 +1,18 @@
 /**
-* @file web_client/http_web_client.h
-* @brief cpp-httplib implementation of the WebClient interface.
-*/
+ * @file web_client/http_web_client.h
+ * @brief cpp-httplib implementation of the WebClient interface.
+ */
 
 #ifndef BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_HTTP_WEB_CLIENT_H_
 #define BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_HTTP_WEB_CLIENT_H_
 
-
-#include "web_client/web_client.h"
-#include "services/logging/logger.h"
-
 #include <memory>
 #include <string>
 #include <utility>
 
+#include "services/logging/logger.h"
+#include "web_client/web_client.h"
+
 /**
  * @brief WebClient implementation backed by cpp-httplib.
  *
@@ -26,9 +25,18 @@
  * bound to a single origin at construction time.
  */
 class HttpWebClient final : public WebClient {
-public:
+ public:
+  /**
+   * @brief Construct an HTTP web client with a logger.
+   *
+   * @param logger Logger instance for diagnostics.
+   */
   explicit HttpWebClient(std::shared_ptr<ILogger> logger)
       : logger_(std::move(logger)) {}
+
+  /**
+   * @brief Destructor.
+   */
   ~HttpWebClient() override = default;
 
   /**
@@ -52,5 +60,4 @@ public:
   std::shared_ptr<ILogger> logger_;
 };
 
-
-#endif
+#endif  // BIERGARTEN_PIPELINE_INCLUDES_WEB_CLIENT_HTTP_WEB_CLIENT_H_