ai_result_handler.h

Go to the documentation of this file.

// BSD 3-Clause License
// Copyright (c) 2021-2025, 🍀☀🌕🌥 🌊
// See the LICENSE file in the project root for full license information.
 
#pragma once
 
#include <kcenon/pacs/core/dicom_dataset.h>
#include <kcenon/pacs/storage/index_database.h>
#include <kcenon/pacs/storage/storage_interface.h>
 
#include <kcenon/common/patterns/result.h>
 
#include <chrono>
#include <cstdint>
#include <functional>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace kcenon::pacs::ai {
 
template <typename T>
using Result = kcenon::common::Result<T>;
 
using VoidResult = kcenon::common::VoidResult;
 
// ─────────────────────────────────────────────────────
// Enumerations
// ─────────────────────────────────────────────────────
 
enum class ai_result_type {
    structured_report,    
    segmentation,         
    presentation_state    
};
 
enum class validation_status {
    valid,                    
    missing_required_tags,    
    invalid_reference,        
    invalid_template,         
    invalid_segment_data,     
    unknown_error             
};
 
// ─────────────────────────────────────────────────────
// Data Structures
// ─────────────────────────────────────────────────────
 
struct ai_result_info {
    std::string sop_instance_uid;
 
    ai_result_type type;
 
    std::string sop_class_uid;
 
    std::string series_instance_uid;
 
    std::string source_study_uid;
 
    std::string algorithm_name;
 
    std::string algorithm_version;
 
    std::chrono::system_clock::time_point received_at;
 
    std::optional<std::string> description;
};
 
struct source_reference {
    std::string study_instance_uid;
 
    std::optional<std::string> series_instance_uid;
 
    std::vector<std::string> sop_instance_uids;
};
 
struct cad_finding {
    std::string finding_type;
 
    std::string location;
 
    std::optional<double> confidence;
 
    std::optional<std::string> measurement;
 
    std::optional<std::string> referenced_sop_instance_uid;
};
 
struct segment_info {
    uint16_t segment_number;
 
    std::string segment_label;
 
    std::optional<std::string> description;
 
    std::string algorithm_type;
 
    std::optional<std::tuple<uint8_t, uint8_t, uint8_t>> recommended_display_color;
};
 
struct validation_result {
    validation_status status;
 
    std::optional<std::string> error_message;
 
    std::vector<std::string> missing_tags;
 
    std::vector<std::string> invalid_references;
};
 
struct ai_handler_config {
    bool validate_source_references = true;
 
    bool validate_sr_templates = true;
 
    bool auto_link_to_source = true;
 
    std::vector<std::string> accepted_sr_templates;
 
    uint16_t max_segments = 256;
};
 
// ─────────────────────────────────────────────────────
// Callback Types
// ─────────────────────────────────────────────────────
 
using ai_result_received_callback = std::function<void(const ai_result_info& info)>;
 
using pre_store_validator = std::function<bool(
    const core::dicom_dataset& dataset,
    ai_result_type type)>;
 
// ─────────────────────────────────────────────────────
// Main Class
// ─────────────────────────────────────────────────────
 
class ai_result_handler {
public:
    [[nodiscard]] static auto create(
        std::shared_ptr<storage::storage_interface> storage,
        std::shared_ptr<storage::index_database> database)
        -> std::unique_ptr<ai_result_handler>;
 
    virtual ~ai_result_handler();
 
    // Non-copyable, movable
    ai_result_handler(const ai_result_handler&) = delete;
    auto operator=(const ai_result_handler&) -> ai_result_handler& = delete;
    ai_result_handler(ai_result_handler&&) noexcept;
    auto operator=(ai_result_handler&&) noexcept -> ai_result_handler&;
 
    // ========================================================================
    // Configuration
    // ========================================================================
 
    void configure(const ai_handler_config& config);
 
    [[nodiscard]] auto get_config() const -> ai_handler_config;
 
    void set_received_callback(ai_result_received_callback callback);
 
    void set_pre_store_validator(pre_store_validator validator);
 
    // ========================================================================
    // Structured Report (SR) Operations
    // ========================================================================
 
    [[nodiscard]] auto receive_structured_report(const core::dicom_dataset& sr)
        -> VoidResult;
 
    [[nodiscard]] auto validate_sr_template(const core::dicom_dataset& sr)
        -> validation_result;
 
    [[nodiscard]] auto get_cad_findings(std::string_view sr_sop_instance_uid)
        -> Result<std::vector<cad_finding>>;
 
    // ========================================================================
    // Segmentation (SEG) Operations
    // ========================================================================
 
    [[nodiscard]] auto receive_segmentation(const core::dicom_dataset& seg)
        -> VoidResult;
 
    [[nodiscard]] auto validate_segmentation(const core::dicom_dataset& seg)
        -> validation_result;
 
    [[nodiscard]] auto get_segment_info(std::string_view seg_sop_instance_uid)
        -> Result<std::vector<segment_info>>;
 
    // ========================================================================
    // Presentation State (PR) Operations
    // ========================================================================
 
    [[nodiscard]] auto receive_presentation_state(const core::dicom_dataset& pr)
        -> VoidResult;
 
    [[nodiscard]] auto validate_presentation_state(const core::dicom_dataset& pr)
        -> validation_result;
 
    // ========================================================================
    // Source Linking Operations
    // ========================================================================
 
    [[nodiscard]] auto link_to_source(
        std::string_view result_uid,
        std::string_view source_study_uid) -> VoidResult;
 
    [[nodiscard]] auto link_to_source(
        std::string_view result_uid,
        const source_reference& references) -> VoidResult;
 
    [[nodiscard]] auto get_source_reference(std::string_view result_uid)
        -> Result<source_reference>;
 
    // ========================================================================
    // Query Operations
    // ========================================================================
 
    [[nodiscard]] auto find_ai_results_for_study(std::string_view study_instance_uid)
        -> Result<std::vector<ai_result_info>>;
 
    [[nodiscard]] auto find_ai_results_by_type(
        std::string_view study_instance_uid,
        ai_result_type type) -> Result<std::vector<ai_result_info>>;
 
    [[nodiscard]] auto get_ai_result_info(std::string_view sop_instance_uid)
        -> std::optional<ai_result_info>;
 
    [[nodiscard]] auto exists(std::string_view sop_instance_uid) const -> bool;
 
    // ========================================================================
    // Removal Operations
    // ========================================================================
 
    [[nodiscard]] auto remove(std::string_view sop_instance_uid) -> VoidResult;
 
    [[nodiscard]] auto remove_ai_results_for_study(std::string_view study_instance_uid)
        -> Result<std::size_t>;
 
protected:
    ai_result_handler(
        std::shared_ptr<storage::storage_interface> storage,
        std::shared_ptr<storage::index_database> database);
 
private:
    class impl;
    std::unique_ptr<impl> pimpl_;
};
 
}  // namespace kcenon::pacs::ai