Module reflection 

ERL-inspired experiential reflection types and pure helpers.

This module adapts the high-level loop from Experiential Reinforcement Learning (ERL) into Gestura’s pipeline model:

1. Experience — the agent makes an initial attempt and observes tool outcomes plus any obvious failure signals.
2. Reflection — when the response quality score falls below a configured threshold, the runtime asks the model for a structured explanation of what went wrong and how to improve.
3. Consolidation — the resulting reflection can be reused within the same turn, stored in session working memory, and promoted into long-term memory for later prompt injection.

This crate owns the portable pieces of that design:

• reflection configuration and data structures
• quality-signal extraction and heuristic scoring
• prompt construction for reflection generation
• parsing of the structured reflection response format

The concrete runtime integration lives in gestura-core/src/pipeline/reflection.rs, which wires these helpers into the agent loop, streaming events, session storage, and memory-bank promotion.

Structs

AgentReflection

A structured reflection generated after a suboptimal agent turn.

QualitySignals

Heuristic quality signals extracted from an agent response.

ReflectionConfig

Configuration for the experiential reflection system.

Functions

build_reflection_prompt

Build the reflection prompt that asks the LLM to analyze a suboptimal turn.

detect_failure_patterns

Check if response text contains common failure/apology patterns.

merge_outcome_signals

Merge outcome signals, replacing older entries of the same kind with the newest.

parse_reflection_response

Parse a structured reflection from an LLM response.

quality_signals_for_response

Build heuristic quality signals from an agent response.

reflection_promotion_confidence

Score how strongly a reflection should be promoted into durable memory.

score_reflection_improvement

Score how much a reflection-guided retry improved quality.