agents.reflection.agent¶

Reflection agents using generic pre/post hook pattern.

Classes¶

`ExpertAgent`	Agent with configurable expertise.
`GradedReflectionMultiAgent`	Grade → Main → Reflect pattern.
`GradingAgent`	Agent that grades responses with structured output.
`PrePostMultiAgent`	Generic pre/post hook multi-agent pattern.
`ReflectionAgent`	Simple reflection agent for improving responses.
`ReflectionMultiAgent`	Any agent with reflection post-processing.
`StructuredOutputMultiAgent`	Any agent followed by structured output extraction.
`ToolBasedReflectionAgent`	Reflection agent that uses tools to cite improvements.

Functions¶

`create`(args, *kwargs)	Create a basic reflection agent (alias for create_reflection_agent).
`create_expert_agent`(name, domain[, expertise_level])	Create an expert agent.
`create_graded_reflection_agent`([name, main_agent])	Create grading agent or full graded reflection system.
`create_reflection_agent`([name, engine])	Create a simple reflection agent.
`create_tool_based_reflection_agent`([name, tools])	Create tool-based reflection agent.
`model_post_init`(args, *kwargs)	Model post-init function (placeholder for compatibility).

Module Contents¶

class agents.reflection.agent.ExpertAgent(/, **data)¶

Bases: haive.agents.simple.agent.SimpleAgent

Agent with configurable expertise.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

model_post_init(__context)¶

Set up expert prompt from config.

Parameters:: __context (Any)
Return type:: None

class agents.reflection.agent.GradedReflectionMultiAgent¶

Bases: PrePostMultiAgent[haive.agents.simple.agent.SimpleAgent, TMainAgent, haive.agents.simple.agent.SimpleAgent]

Grade → Main → Reflect pattern.

Pattern: 1. Main agent responds 2. Grading agent evaluates (with structured output) 3. Message transform for reflection 4. Reflection agent improves based on grade

classmethod create(main_agent, name=None, grading_system_prompt=GRADING_SYSTEM_PROMPT, reflection_system_prompt=REFLECTION_SYSTEM_PROMPT, **kwargs)¶

Create graded reflection multi-agent.

Parameters:

main_agent (TMainAgent)
name (str | None)
grading_system_prompt (str)
reflection_system_prompt (str)

Return type:

GradedReflectionMultiAgent

class agents.reflection.agent.GradingAgent(/, **data)¶

Bases: haive.agents.simple.agent.SimpleAgent

Agent that grades responses with structured output.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

model_post_init(__context)¶

Set up grading configuration.

Parameters:: __context (Any)
Return type:: None

class agents.reflection.agent.PrePostMultiAgent¶

Bases: haive.agents.multi.base.agent.MultiAgent, Generic[TPreAgent, TMainAgent, TPostAgent]

Generic pre/post hook multi-agent pattern.

This provides a general pattern for: - Pre-processing (optional) - Main processing - Post-processing (optional)

With optional message transformation between stages.

model_post_init(__context)¶

Set up the agents list.

Parameters:: __context (Any)
Return type:: None

class agents.reflection.agent.ReflectionAgent(/, **data)¶

Bases: haive.agents.simple.agent.SimpleAgent

Simple reflection agent for improving responses.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

model_post_init(__context)¶

Set up reflection prompt.

Parameters:: __context (Any)
Return type:: None

class agents.reflection.agent.ReflectionMultiAgent¶

Bases: PrePostMultiAgent[haive.agents.base.agent.Agent, TMainAgent, haive.agents.simple.agent.SimpleAgent]

Any agent with reflection post-processing.

Pattern: 1. Main agent responds 2. Message transform (AI → Human) 3. Reflection agent improves response

classmethod create(main_agent, name=None, reflection_system_prompt=REFLECTION_SYSTEM_PROMPT, **kwargs)¶

Create reflection multi-agent.

Parameters:

main_agent (TMainAgent)
name (str | None)
reflection_system_prompt (str)

Return type:

ReflectionMultiAgent

class agents.reflection.agent.StructuredOutputMultiAgent¶

Bases: PrePostMultiAgent[haive.agents.base.agent.Agent, TMainAgent, haive.agents.structured.StructuredOutputAgent]

Any agent followed by structured output extraction.

This is the pattern we already have: - Main agent produces unstructured output - StructuredOutputAgent extracts structure

classmethod create(main_agent, output_model, name=None, **kwargs)¶

Create with main agent and output model.

Parameters:

main_agent (TMainAgent)
output_model (type[pydantic.BaseModel])
name (str | None)

Return type:

StructuredOutputMultiAgent

class agents.reflection.agent.ToolBasedReflectionAgent(/, **data)¶

Bases: haive.agents.react.agent.ReactAgent

Reflection agent that uses tools to cite improvements.

Similar to LangChain’s reflexion but more flexible.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Parameters:: data (Any)

model_post_init(__context)¶

Set up tool-based reflection.

Parameters:: __context (Any)
Return type:: None

agents.reflection.agent.create(*args, **kwargs)¶: Create a basic reflection agent (alias for create_reflection_agent).

agents.reflection.agent.create_expert_agent(name, domain, expertise_level='expert', **kwargs)¶

Create an expert agent.

Parameters:

name (str)
domain (str)
expertise_level (Literal['beginner', 'intermediate', 'expert', 'world-class'])

Return type:

ExpertAgent

agents.reflection.agent.create_graded_reflection_agent(name='graded_reflector', main_agent=None, **kwargs)¶

Create grading agent or full graded reflection system.

Parameters:

name (str)
main_agent (haive.agents.base.agent.Agent | None)

Return type:

GradingAgent | GradedReflectionMultiAgent

agents.reflection.agent.create_reflection_agent(name='reflector', engine=None, **kwargs)¶

Create a simple reflection agent.

Parameters:

name (str)
engine (haive.core.engine.aug_llm.AugLLMConfig | None)

Return type:

ReflectionAgent

agents.reflection.agent.create_tool_based_reflection_agent(name='tool_reflector', tools=None, **kwargs)¶

Create tool-based reflection agent.

Parameters:

name (str)
tools (list | None)

Return type:

ToolBasedReflectionAgent

agents.reflection.agent.model_post_init(*args, **kwargs)¶: Model post-init function (placeholder for compatibility).