constitutional_validator.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
#pragma once
 
#include <entropic/interfaces/i_hook_handler.h>
#include <entropic/interfaces/i_inference_callbacks.h>
#include <entropic/types/config.h>
#include <entropic/types/error.h>
#include <entropic/types/hooks.h>
#include <entropic/types/validation.h>
 
#include <atomic>
#include <functional>
#include <mutex>
#include <utility>
#include <optional>
#include <string>
#include <unordered_map>
 
namespace entropic {
 
struct ValidationContext {
    class ConstitutionalValidator* validator; 
    InferenceInterface* inference;            
};
 
class ConstitutionalValidator {
public:
    ConstitutionalValidator(
        const ConstitutionalValidationConfig& config,
        const std::string& constitution_text);
 
    entropic_error_t attach(
        HookInterface* hook_iface,
        InferenceInterface* inference);
 
    void detach(HookInterface* hook_iface);
 
    bool should_validate(const std::string& identity_name) const;
 
    void set_identity_validation(
        const std::string& identity_name, bool enabled);
 
    void set_tier_rules(
        const std::string& identity_name,
        const std::vector<std::string>& rules);
 
    void set_global_enabled(bool enabled);
 
    void set_marker_resolver(
        std::function<std::pair<std::string, std::string>(
            const std::string&)> resolver);
 
    ValidationResult validate(
        const std::string& content,
        const std::string& tier,
        const char* messages_json);
 
    ValidationResult last_result() const;
 
    // ── gh#30 (v2.1.5): consumer-driven retry controls ──────
 
    void set_auto_retry(bool enabled);
 
    bool auto_retry_enabled() const;
 
    entropic_error_t resume_retry();
 
    entropic_error_t accept_last();
 
    void set_attempt_boundary_cb(
        void (*cb)(int attempt_n, void* user_data), void* user_data);
 
    void set_critique_callbacks(
        void (*start_cb)(void* user_data),
        void (*end_cb)(void* user_data),
        void* user_data);
 
    const ConstitutionalValidationConfig& config() const { return config_; }
 
    static int hook_callback(
        entropic_hook_point_t hook_point,
        const char* context_json,
        char** modified_json,
        void* user_data);
 
    std::string build_critique_prompt(const std::string& content) const;
 
    void append_turn_evidence(std::string& prompt) const;
 
    static CritiqueResult parse_critique(const std::string& json_str);
 
private:
    CritiqueResult run_critique(const std::string& content);
 
    std::string build_critique_messages(const std::string& content) const;
 
    std::string build_critique_params() const;
 
    std::string revise(
        const std::string& original,
        const CritiqueResult& critique,
        const char* messages_json);
 
    void store_result(const ValidationResult& result);
 
    void log_verdict(const ValidationResult& result) const;
 
    ValidationResult run_validation_loop(
        const std::string& content,
        const std::string& tier,
        const char* messages_json);
 
    ValidationResult apply_revisions(
        ValidationResult result,
        const CritiqueResult& initial_critique,
        const char* messages_json);
 
    std::string attempt_revision(
        const std::string& content,
        const CritiqueResult& critique,
        const char* messages_json);
 
    std::string build_single_turn_json(
        const std::string& prompt) const;
 
    std::string build_revision_messages(
        const std::string& original,
        const CritiqueResult& critique,
        const char* messages_json) const;
 
    std::string build_feedback_text(
        const CritiqueResult& critique) const;
 
    std::string inject_feedback_into_messages(
        const std::string& original,
        const std::string& feedback,
        const char* messages_json) const;
 
    int handle_hook(const char* context_json, char** modified_json);
 
    static void write_modified_json(
        const std::string& content, char** modified_json);
 
    static std::string extract_json_string(
        const char* json, const char* key);
 
    static std::string extract_string_after_colon(const char* pos);
 
    static bool extract_compliant_field(
        const std::string& json, CritiqueResult& result);
 
    static void extract_violations(
        const std::string& json, CritiqueResult& result);
 
    static std::optional<Violation> extract_next_violation(
        const std::string& json, size_t& pos);
 
    static void extract_revised_field(
        const std::string& json, CritiqueResult& result);
 
    ConstitutionalValidationConfig config_;   
    std::string constitution_text_;           
    InferenceInterface* inference_ = nullptr; 
    ValidationContext context_;                
 
    bool global_enabled_;
    std::function<std::pair<std::string, std::string>(const std::string&)>
        marker_resolver_;
    mutable std::mutex marker_mutex_;  
    std::unordered_map<std::string, bool> identity_overrides_;
    std::unordered_map<std::string, std::vector<std::string>> tier_rules_;
    mutable std::mutex overrides_mutex_;      
 
    static const std::string& current_tier();
    static const std::string& current_tool_context();
    static const std::string& current_tool_evidence();
    static const std::string& current_system_prompt();
    static void set_turn_context(const std::string& tier,
                                 const std::string& tool_context,
                                 const std::string& tool_evidence,
                                 const std::string& system_prompt);
 
    ValidationResult last_result_;
    mutable std::mutex result_mutex_;         
 
    // ── gh#30 (v2.1.5): consumer-driven retry controls ─────
    std::atomic<bool> auto_retry_enabled_{true};
 
    struct PendingValidationState {
        ValidationResult result;       
        CritiqueResult critique;       
        std::string messages_json;     
        std::string tier;              
        std::string system_prompt;
    };
    std::optional<PendingValidationState> pending_state_;
    mutable std::mutex pending_mutex_;        
 
    struct AttemptBoundaryCb {
        void (*cb)(int, void*) = nullptr;
        void* user_data = nullptr;
    };
    AttemptBoundaryCb attempt_boundary_;
    mutable std::mutex attempt_boundary_mutex_;
 
    struct CritiqueCallbacks {
        void (*start_cb)(void*) = nullptr;
        void (*end_cb)(void*) = nullptr;
        void* user_data = nullptr;
    };
    CritiqueCallbacks critique_cbs_;
    mutable std::mutex critique_cbs_mutex_;
};
 
} // namespace entropic