agents.reflection.message_transformer_posthook

Message Transformer Reflection Post-Hook Pattern.

This implements the correct reflection pattern using message transformation as a POST-HOOK following the insights from 2025-01-18:

  1. Don’t fight the message-only interface - use prompt engineering instead

  2. Structured data flows through prompt configuration, not messages

  3. Message transformation + prompt partials = powerful combination

  4. The flow: Main Agent → Response → Convert to prompt partial → Message Transform → Reflection

This follows the pattern documented in: - project_docs/memory_index/by_date/2025-01-18/reflection_pattern_insights.md - project_docs/sessions/active/hook_pattern_conceptual_exploration.md

Classes

AgentWithPostHook

Agent wrapper that applies post-hooks after execution.

MessageTransformerPostHook

Post-hook that applies message transformation for reflection.

ReflectionWithGradePostHook

Post-hook that combines grading + message transformation + reflection.

Functions

create_agent_with_reflection(base_agent[, reflection_type])

Create an agent with reflection post-hook.

create_graded_reflection_post_hook(grading_model[, ...])

Create a graded reflection post-hook.

create_reflection_post_hook([...])

Create a basic reflection post-hook.

example_basic_post_hook()

Example: Basic message transformer post-hook.

example_factory_pattern()

Example: Using factory function for quick setup.

example_graded_reflection_post_hook()

Example: Graded reflection with message transformation.

main()

Run all post-hook examples.

Module Contents

class agents.reflection.message_transformer_posthook.AgentWithPostHook(base_agent, post_hooks=None)

Agent wrapper that applies post-hooks after execution.

This implements the proper hook pattern where: 1. Base agent executes normally 2. Post-hooks transform the result 3. Enhanced result is returned

Initialize agent with post-hooks.

Parameters:

  • base_agent (haive.agents.simple.agent.SimpleAgent) – The base agent to wrap

  • post_hooks (list[MessageTransformerPostHook] | None) – List of post-hooks to apply

add_post_hook(hook)

Add a post-hook.

Parameters:

hook (MessageTransformerPostHook)

async arun(input_data)

Run agent with post-hook processing.

Parameters:

input_data (Any) – Input for the base agent

Returns:

Result after all post-hooks have been applied

Return type:

dict[str, Any]

class agents.reflection.message_transformer_posthook.MessageTransformerPostHook(reflection_agent, transform_type='reflection', preserve_first_message=True)

Post-hook that applies message transformation for reflection.

This follows the correct pattern: 1. Agent produces response (messages) 2. Extract structured data from messages 3. Convert to prompt partial (NOT message!) 4. Apply message transformation 5. Feed to reflection agent with grade in prompt context

Initialize the post-hook.

Parameters:

  • reflection_agent (haive.agents.simple.agent.SimpleAgent) – Agent that will do the reflection

  • transform_type (str) – Type of message transformation to apply

  • preserve_first_message (bool) – Whether to preserve first message

class agents.reflection.message_transformer_posthook.ReflectionWithGradePostHook(grading_agent, reflection_agent, preserve_first_message=True)

Bases: MessageTransformerPostHook

Post-hook that combines grading + message transformation + reflection.

This implements the exact pattern from the 2025-01-18 insights: Main Agent → Response → GradingResult → Convert to prompt partial → Message Transform → Reflection Agent (with grade in prompt context)

Initialize graded reflection post-hook.

Parameters:

  • grading_agent (haive.agents.simple.agent.SimpleAgent) – Agent that produces structured grading

  • reflection_agent (haive.agents.simple.agent.SimpleAgent) – Agent that does reflection with grade context

  • preserve_first_message (bool) – Whether to preserve first message

agents.reflection.message_transformer_posthook.create_agent_with_reflection(base_agent, reflection_type='basic')

Create an agent with reflection post-hook.

Parameters:

  • base_agent (haive.agents.simple.agent.SimpleAgent) – The base agent to enhance

  • reflection_type (str) – Type of reflection (“basic” or “graded”)

Returns:

Agent wrapped with reflection post-hook

Return type:

AgentWithPostHook

agents.reflection.message_transformer_posthook.create_graded_reflection_post_hook(grading_model, temperature=0.2)

Create a graded reflection post-hook.

Parameters:

  • grading_model (type[pydantic.BaseModel])

  • temperature (float)

Return type:

ReflectionWithGradePostHook

agents.reflection.message_transformer_posthook.create_reflection_post_hook(reflection_prompt_template=None, temperature=0.3)

Create a basic reflection post-hook.

Parameters:

  • reflection_prompt_template (langchain_core.prompts.ChatPromptTemplate | None)

  • temperature (float)

Return type:

MessageTransformerPostHook

async agents.reflection.message_transformer_posthook.example_basic_post_hook()

Example: Basic message transformer post-hook.

async agents.reflection.message_transformer_posthook.example_factory_pattern()

Example: Using factory function for quick setup.

async agents.reflection.message_transformer_posthook.example_graded_reflection_post_hook()

Example: Graded reflection with message transformation.

async agents.reflection.message_transformer_posthook.main()

Run all post-hook examples.