Post-generation constitutional compliance validator. More...

#include <entropic/core/constitutional_validator.h>

Public Member Functions
	ConstitutionalValidator (const ConstitutionalValidationConfig &config, const std::string &constitution_text)
	Construct validator with config and constitution text.

entropic_error_t	attach (HookInterface hook_iface, InferenceInterface inference)
	Register this validator as a POST_GENERATE hook.

void	detach (HookInterface *hook_iface)
	Deregister the POST_GENERATE hook.

bool	should_validate (const std::string &identity_name) const
	Check if validation is enabled for a given identity.

void	set_identity_validation (const std::string &identity_name, bool enabled)
	Set per-identity validation override.

void	set_tier_rules (const std::string &identity_name, const std::vector< std::string > &rules)
	Set per-identity validation rules from frontmatter.

void	set_global_enabled (bool enabled)
	Toggle the global validation gate at runtime.

ValidationResult	validate (const std::string &content, const std::string &tier, const char *messages_json)
	Run the validation pipeline on generated content.

ValidationResult	last_result () const
	Get the last validation result.

void	set_auto_retry (bool enabled)
	Enable or disable automatic revision after rejection.

bool	auto_retry_enabled () const
	Whether auto-revision is currently enabled.

entropic_error_t	resume_retry ()
	Resume the revision pass after a paused validation.

entropic_error_t	accept_last ()
	Finalize the cached attempt as the validation result.

void	set_attempt_boundary_cb (void(cb)(int attempt_n, void user_data), void *user_data)
	Register the attempt-boundary callback.

void	set_critique_callbacks (void(start_cb)(void user_data), void(end_cb)(void user_data), void *user_data)
	Register the critique start/end callback pair (gh#50).

const ConstitutionalValidationConfig &	config () const
	Get the config (read-only after construction).

std::string	build_critique_prompt (const std::string &content) const
	Build the critique prompt (exposed for testing).

Static Public Member Functions
static int	hook_callback (entropic_hook_point_t hook_point, const char context_json, char modified_json, void user_data)
	POST_GENERATE hook callback for constitutional validation.

static CritiqueResult	parse_critique (const std::string &json_str)
	Parse critique JSON into structured result (exposed for testing).

Detailed Description

Post-generation constitutional compliance validator.

Evaluates engine output against constitutional rules using a grammar-constrained critique generation pass, parses a structured JSON verdict, and optionally re-generates with feedback when violations are found.

Usage: ConstitutionalValidator validator(config, constitution_text);

validator.attach(&hook_registry, &inference);

// ... engine runs, POST_GENERATE hook triggers validation ...

validator.detach(&hook_registry);

entropic::ConstitutionalValidator
Post-generation constitutional compliance validator.
Definition constitutional_validator.h:82

entropic::ConstitutionalValidator::config
const ConstitutionalValidationConfig & config() const
Get the config (read-only after construction).
Definition constitutional_validator.h:282

Version: 1.9.8

Definition at line 82 of file constitutional_validator.h.

Constructor & Destructor Documentation

◆ ConstitutionalValidator()

entropic::ConstitutionalValidator::ConstitutionalValidator	(	const ConstitutionalValidationConfig &	config,
		const std::string &	constitution_text
	)

Construct validator with config and constitution text.

Parameters

config	Validation pipeline configuration.
constitution_text	Full constitution text (from PromptManager).

Version: 1.9.8

Parameters

config	Validation pipeline configuration.
constitution_text	Full constitution text.

Version: 2.0.4

Definition at line 36 of file constitutional_validator.cpp.

Member Function Documentation

◆ accept_last()

entropic_error_t entropic::ConstitutionalValidator::accept_last ( )

Finalize the cached attempt as the validation result.

Finalize the paused attempt as the consumer-accepted answer.

Used after set_auto_retry(false) paused validation: marks the paused attempt as the consumer-accepted answer (verdict becomes passed_consumer_override) and clears the cached pending state.

Returns: ENTROPIC_OK on success. ENTROPIC_ERROR_INVALID_STATE if no validation is paused.

Version: 2.1.5

Marks verdict as passed_consumer_override and clears pending state. Returns INVALID_STATE if no pending state exists.

Returns: ENTROPIC_OK on success.

Definition at line 187 of file constitutional_validator.cpp.

◆ attach()

entropic_error_t entropic::ConstitutionalValidator::attach	(	HookInterface *	hook_iface,
		InferenceInterface *	inference
	)

Register this validator as a POST_GENERATE hook.

Register as POST_GENERATE hook via the HookRegistry C API.

Parameters

hook_iface	HookInterface for registration (via fire_post).
inference	InferenceInterface for critique generation.

Returns: ENTROPIC_OK on success.

Version: 1.9.8

Parameters

hook_iface	HookInterface with registry pointer.
inference	InferenceInterface for critique generation.

Returns: ENTROPIC_OK on success.

Definition at line 54 of file constitutional_validator.cpp.

◆ auto_retry_enabled()

bool entropic::ConstitutionalValidator::auto_retry_enabled ( ) const

Whether auto-revision is currently enabled.

Read auto-revision flag.

Returns: true if enabled. @utility

Version: 2.1.5

Returns: Current state. @utility

Version: 2.1.5

Definition at line 142 of file constitutional_validator.cpp.

◆ build_critique_prompt()

std::string entropic::ConstitutionalValidator::build_critique_prompt ( const std::string & content ) const

Build the critique prompt (exposed for testing).

Build the critique prompt string.

Parameters

content Text to critique.

Returns: Formatted critique prompt string.

Version: 1.9.8

When per-tier validation_rules exist (from identity frontmatter), those are the PRIMARY evaluation criteria and the constitution is included as background context. This prevents the validator from citing global constitution rule numbers ("Rule 2: Tool calls are mandatory") when the tier has its own specific compliance criteria.

When no validation_rules exist, falls back to the constitution as the sole rubric (pre-v2.0.8 behavior).

Prepends a tool call manifest (from current_tool_context_) when available so the validator can distinguish grounded claims from ungrounded assertions.

Parameters

content Text to critique (think blocks already stripped).

Returns: Formatted critique prompt string. @utility

Version: 2.1.3

Definition at line 418 of file constitutional_validator.cpp.

◆ config()

const ConstitutionalValidationConfig & entropic::ConstitutionalValidator::config ( ) const

inline

Get the config (read-only after construction).

Returns: Reference to config. @utility

Version: 1.9.8

Definition at line 282 of file constitutional_validator.h.

◆ detach()

void entropic::ConstitutionalValidator::detach ( HookInterface * hook_iface )

Deregister the POST_GENERATE hook.

Parameters

hook_iface HookInterface for deregistration.

Version: 1.9.8

Parameters

hook_iface HookInterface with registry pointer.

Definition at line 78 of file constitutional_validator.cpp.

◆ hook_callback()

int entropic::ConstitutionalValidator::hook_callback	(	entropic_hook_point_t	hook_point,
		const char *	context_json,
		char **	modified_json,
		void *	user_data
	)

static

POST_GENERATE hook callback for constitutional validation.

POST_GENERATE hook callback.

Static function registered with HookRegistry. Extracts ValidationContext from user_data, runs the validation pipeline, and writes modified_json if content was revised.

Parameters

hook_point	Hook point (POST_GENERATE).
context_json	JSON context from engine.
modified_json	Output: revised JSON or NULL.
user_data	ValidationContext pointer.

Returns: 0 (post-hooks cannot cancel). @callback

Version: 1.9.8

Parameters

hook_point	Hook point (POST_GENERATE).
context_json	JSON context from engine.
modified_json	Output: revised JSON or NULL.
user_data	ValidationContext pointer.

Returns: 0 (post-hooks cannot cancel). @callback

Version: 1.9.8

Definition at line 381 of file constitutional_validator.cpp.

◆ last_result()

ValidationResult entropic::ConstitutionalValidator::last_result ( ) const

Get the last validation result.

Returns: Most recent ValidationResult, or default if none.

Version: 1.9.8

Returns: Most recent ValidationResult.

Definition at line 364 of file constitutional_validator.cpp.

◆ parse_critique()

CritiqueResult entropic::ConstitutionalValidator::parse_critique ( const std::string & json_str )

static

Parse critique JSON into structured result (exposed for testing).

Parse critique JSON into CritiqueResult.

Parameters

json_str Raw JSON string from grammar-constrained generation.

Returns: Parsed CritiqueResult.

Version: 1.9.8

Parameters

json_str Raw JSON from grammar-constrained generation.

Returns: Parsed CritiqueResult. On parse failure, returns default (compliant=true) with raw_json set for diagnostics. @utility

Version: 2.0.6

Definition at line 480 of file constitutional_validator.cpp.

◆ resume_retry()

entropic_error_t entropic::ConstitutionalValidator::resume_retry ( )

Resume the revision pass after a paused validation.

Resume the revision loop after a paused validation.

Re-enters apply_revisions() using the state cached by the most recent validate() call that paused on a critique failure. Runs synchronously and updates last_result_. Returns ENTROPIC_ERROR_INVALID_STATE if no validation is paused.

Returns: ENTROPIC_OK on success.

Version: 2.1.5

Pops the cached pending state, runs apply_revisions() against it ignoring the auto_retry_enabled_ flag for this call, and stores the final result. Returns INVALID_STATE if no pending state exists.

Returns: ENTROPIC_OK on success, INVALID_STATE if nothing paused.

Definition at line 157 of file constitutional_validator.cpp.

◆ set_attempt_boundary_cb()

void entropic::ConstitutionalValidator::set_attempt_boundary_cb	(	void()(int attempt_n, void user_data)	cb,
		void *	user_data
	)

Register the attempt-boundary callback.

Fires immediately before each revision attempt starts. Used by consumers to split rendered output between attempts.

Parameters

cb	Callback (nullable clears).
user_data	Forwarded to `cb`.

Version: 2.1.5

Parameters

cb	Callback fn pointer.
user_data	Forwarded to cb.

Definition at line 212 of file constitutional_validator.cpp.

◆ set_auto_retry()

void entropic::ConstitutionalValidator::set_auto_retry ( bool enabled )

Enable or disable automatic revision after rejection.

Toggle auto-revision.

When disabled, validate() returns immediately on the first failing critique with verdict paused_pending_consumer and caches enough state for resume_retry() to continue the revision loop later. Default: true (preserves pre-2.1.5 behavior).

Parameters

enabled Whether auto-revision is enabled.

Version: 2.1.5

Parameters

enabled True to enable auto-revision.

Definition at line 132 of file constitutional_validator.cpp.

◆ set_critique_callbacks()

void entropic::ConstitutionalValidator::set_critique_callbacks	(	void()(void user_data)	start_cb,
		void()(void user_data)	end_cb,
		void *	user_data
	)

Register the critique start/end callback pair (gh#50).

Register critique start/end callbacks (gh#50, v2.1.12).

Fires immediately before and after the synchronous inference_->generate() call inside run_critique(). Gives consumer UIs a visible signal for the 20-30s critique window that previously left AgentState parked at EXECUTING with no observable transition. Both callbacks take only the user_data pointer — consumer correlates timing themselves.

Persistent-slot pattern: outlives set_callbacks() shuffles (validator owns its own slot, no entanglement with EngineCallbacks). Same survival contract as set_attempt_boundary_cb and the v2.1.10 state observer.

start_cb and end_cb are nullable independently; passing nullptr for both clears the slot.

Parameters

start_cb	Fires before the critique generate begins.
end_cb	Fires after the critique generate returns.
user_data	Forwarded to both callbacks. @threadsafety Thread-safe (guarded by critique_cbs_mutex_).

Version: 2.1.12

Stored under critique_cbs_mutex_ so a consumer reassigning the slot cannot race with the firing site in run_critique(). Either callback pointer may be nullptr independently — only the non-null ones fire.

Parameters

start_cb	Pre-generate hook.
end_cb	Post-generate hook.
user_data	Forwarded to both.

Definition at line 233 of file constitutional_validator.cpp.

◆ set_global_enabled()

void entropic::ConstitutionalValidator::set_global_enabled ( bool enabled )

Toggle the global validation gate at runtime.

Per-identity overrides set via set_identity_validation() still take precedence; this only changes the fallback value used when no per-identity override exists.

Parameters

enabled true to enable validation globally, false to disable. @req REQ-VALID-004

Version: 2.0.2

Parameters

enabled New global enable state. @req REQ-VALID-004

Version: 2.0.4

Definition at line 119 of file constitutional_validator.cpp.

◆ set_identity_validation()

void entropic::ConstitutionalValidator::set_identity_validation	(	const std::string &	identity_name,
		bool	enabled
	)

Set per-identity validation override.

Parameters

identity_name	Identity name.
enabled	Whether validation is enabled for this identity.

Version: 1.9.8

Parameters

identity_name	Identity name.
enabled	Whether validation is enabled.

Definition at line 250 of file constitutional_validator.cpp.

◆ set_tier_rules()

void entropic::ConstitutionalValidator::set_tier_rules	(	const std::string &	identity_name,
		const std::vector< std::string > &	rules
	)

Set per-identity validation rules from frontmatter.

Parameters

identity_name	Identity/tier name.
rules	Validation rules specific to this identity.

Version: 2.0.6

Parameters

identity_name	Identity/tier name.
rules	Validation rules for this identity.

Definition at line 263 of file constitutional_validator.cpp.

◆ should_validate()

bool entropic::ConstitutionalValidator::should_validate ( const std::string & identity_name ) const

Check if validation is enabled for a given identity.

Returns false if the tier is in config_.skip_tiers (e.g. "lead"). Per-identity overrides (set_identity_validation) take precedence.

Parameters

identity_name Identity name to check.

Returns: true if validation should run for this identity.

Version: 2.0.7

Returns false if the tier is in config_.skip_tiers (e.g. "lead", which streams output before the POST_GENERATE hook fires). Per-identity overrides take precedence over skip_tiers.

Parameters

identity_name Identity name to check.

Returns: true if validation should run.

Definition at line 99 of file constitutional_validator.cpp.

◆ validate()

ValidationResult entropic::ConstitutionalValidator::validate	(	const std::string &	content,
		const std::string &	tier,
		const char *	messages_json
	)

Run the validation pipeline on generated content.

Run the full validation pipeline on generated content.

Parameters

content	The generated text to validate.
tier	The tier/identity that produced the content.
messages_json	The conversation context (for revision).

Returns: ValidationResult with final content and critique metadata.

Called from the POST_GENERATE hook callback. Flow:

Check per-identity override
Run critique generation pass
Parse structured JSON verdict
If violations and revision enabled, revise
Return final (possibly revised) content

Version: 1.9.8

When called from handle_hook(), current_tool_context_ and current_system_prompt_ are set before this call so that build_critique_prompt() and inject_feedback_into_messages() have the per-turn context they need.

Parameters

content	The generated text to validate.
tier	The tier/identity that produced the content.
messages_json	Original conversation context.

Returns: ValidationResult with final content and critique metadata.

Definition at line 285 of file constitutional_validator.cpp.

The documentation for this class was generated from the following files:

entropic/core/constitutional_validator.h
core/constitutional_validator.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ConstitutionalValidator()

Member Function Documentation

◆ accept_last()

◆ attach()

◆ auto_retry_enabled()

◆ build_critique_prompt()

◆ config()

◆ detach()

◆ hook_callback()

◆ last_result()

◆ parse_critique()

◆ resume_retry()

◆ set_attempt_boundary_cb()

◆ set_auto_retry()

◆ set_critique_callbacks()

◆ set_global_enabled()

◆ set_identity_validation()

◆ set_tier_rules()

◆ should_validate()

◆ validate()