Struct StructuredOutputEngine 

pub struct StructuredOutputEngine { /* private fields */ }

Post-processing structured output validation engine (Layers 2-4)

Attempts validation through multiple layers until success or exhaustion. All attempts are tracked via events for observability.

Layer 0 (DynamicSubmitTool injection) is handled externally in executor/verbs.rs and rig_agent_loop/mod.rs BEFORE this engine is invoked.

Layers (this engine)

• Layer 2: Extract + Validate - extracts JSON from raw output and validates against schema
• Layer 3: Retry with Feedback - re-calls LLM with validation errors (requires infer_fn)
• Layer 4: LLM Repair - calls repair model to fix invalid JSON (requires infer_fn)

Without infer_fn, only Layer 2 is functional. Layers 3 & 4 will emit warnings and gracefully skip to the next layer.

Implementations

impl StructuredOutputEngine

pub fn new(spec: StructuredOutputSpec, log: Arc<EventLog>) -> Self

Create a new engine with the given spec and event log

pub fn with_infer_callback(self, callback: InferCallback) -> Self

Set the inference callback for Layer 3 & 4

This enables actual LLM retries and repairs. Without this callback, only Layer 2 validation is functional.

Example

let callback: InferCallback = Arc::new(move |prompt: String| {
    let provider = provider.clone();
    Box::pin(async move {
        provider.infer(&prompt, None).await
            .map_err(|e| NikaError::ProviderApiError { message: e.to_string() })
    })
});
let engine = engine.with_infer_callback(callback);

pub fn with_original_prompt(self, prompt: String) -> Self

Set the original prompt for retry context

Used by Layer 3 to construct the retry prompt with full context.

pub fn with_provider_context(self, provider: String, model: String) -> Self

Set provider and model names for telemetry on Layer 3/4 LLM calls

pub async fn load_schema(&mut self) -> Result<Arc<Value>, NikaError>

Load and cache the schema for validation. Returns an Arc<Value> for cheap cloning across async boundaries.

pub fn schema(&self) -> Option<&SchemaRef>

Get the raw schema reference from the spec.

Returns None when from_example is set (schema derived at runtime). Use load_schema() to get the resolved, effective schema.

pub fn cached_example(&self) -> Option<&Value>

Get the cached example value (set during load_schema() for file-based examples).

Returns Some after load_schema() has been called when from_example is a file. For inline examples, returns None (the value is in spec.from_example directly).

pub async fn validate( &mut self, task_id: &str, raw_output: &str, ) -> Result<StructuredOutputResult, NikaError>

Validate raw output through the 4-layer defense system

Returns the validated JSON value and metadata about which layer succeeded.

pub fn generate_retry_prompt( &self, original_prompt: &str, invalid_output: &str, validation_errors: &str, ) -> String

Generate a retry prompt with validation feedback

Used by Layer 3 to construct the re-prompt with error context.

pub fn generate_repair_prompt( &self, invalid_output: &str, schema: &Value, ) -> String

Generate a repair prompt for Layer 4

Used by the executor to construct the repair LLM call.