agents.rag.models

RAG Agent Models.

This module contains all Pydantic models used by RAG agents for structured data validation and type safety. These models represent different outputs and intermediate results from various RAG patterns.

Example

>>> from haive.agents.rag.models import HyDEResult
>>> result = HyDEResult(
...     hypothetical_doc="Generated document content...",
...     refined_query="Refined query text",
...     confidence=0.85
... )

Typical usage:

• Import specific models for agent implementations

• Use for structured output from LLM engines

• Validate intermediate results in RAG pipelines

• Type hints for function parameters and returns

Classes

BranchResult	Result from a single retrieval branch.
EnhancedResponse	Enhanced response with reasoning and memory integration.
FusionResult	Fusion ranking result from multi-query RAG.
HyDEResult	Hypothetical Document Enhanced (HyDE) result.
MemoryAnalysis	Memory analysis result for context-aware processing.
MemoryEntry	Memory entry for memory-aware RAG systems.
MemoryType	Types of memory for memory-aware RAG.
MergedResult	Final merged result from multiple branches or strategies.
QueryClassification	Query classification result for routing decisions.
QueryPlan	Query planning result for complex query decomposition.
QueryType	Types of queries for branched RAG routing.
RAGModuleType	Types of RAG modules for modular composition.
ReActStep	ReAct pattern step types.
ReActStepResult	Result from a single ReAct pattern step.
SpeculativeResult	Speculative reasoning result with hypothesis verification.
StepBackResult	Step-back reasoning result for abstract thinking.
StrategyDecision	Strategy selection decision for agentic routing.
SubQueryResult	Result from executing a single sub-query.

Module Contents

class agents.rag.models.BranchResult(/, **data)

Bases: pydantic.BaseModel

Result from a single retrieval branch.

Contains results from executing a specific branch in branched RAG, where multiple retrieval strategies are executed in parallel.

Parameters:

data (Any)

branch_type

Type of branch executed.

Type:

str

retrieved_docs

Documents retrieved by this branch.

Type:

List[str]

branch_answer

Answer generated by this branch.

Type:

str

relevance_score

Relevance score for this branch (0.0 to 1.0).

Type:

float

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.

class agents.rag.models.EnhancedResponse(/, **data)

Bases: pydantic.BaseModel

Enhanced response with reasoning and memory integration.

Contains a comprehensive response that includes the main answer, reasoning chain, memory context, and metadata.

Parameters:

data (Any)

answer

Main answer to the query.

Type:

str

reasoning_chain

ReAct reasoning steps taken.

Type:

List[ReActStepResult]

memory_used

Memories used in generating response.

Type:

List[MemoryEntry]

new_memories

New memories to store from this interaction.

Type:

List[MemoryEntry]

confidence

Response confidence (0.0 to 1.0).

Type:

float

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.

class agents.rag.models.FusionResult(/, **data)

Bases: pydantic.BaseModel

Fusion ranking result from multi-query RAG.

Contains documents ranked using reciprocal rank fusion or similar techniques for combining multiple retrieval results.

Parameters:

data (Any)

fused_documents

Documents ranked by fusion algorithm.

Type:

List[str]

fusion_scores

Corresponding fusion scores.

Type:

List[float]

ranking_method

Method used for ranking (e.g., “reciprocal_rank_fusion”).

Type:

str

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.

class agents.rag.models.HyDEResult(/, **data)

Bases: pydantic.BaseModel

Hypothetical Document Enhanced (HyDE) result.

Contains the generated hypothetical document and refined query used in the HyDE RAG pattern for improved retrieval performance.

Parameters:

data (Any)

hypothetical_doc

Generated hypothetical document that would answer the query.

Type:

str

refined_query

Query refined based on the hypothetical document.

Type:

str

confidence

Confidence score in the hypothesis (0.0 to 1.0).

Type:

float

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.

class agents.rag.models.MemoryAnalysis(/, **data)

Bases: pydantic.BaseModel

Memory analysis result for context-aware processing.

Contains analysis of relevant memories and identified knowledge gaps for enhanced context-aware response generation.

Parameters:

data (Any)

relevant_memories

Relevant memories found.

Type:

List[MemoryEntry]

memory_gaps

Identified knowledge gaps.

Type:

List[str]

temporal_context

Temporal context of memories.

Type:

str

confidence

Overall memory confidence (0.0 to 1.0).

Type:

float

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.

class agents.rag.models.MemoryEntry(/, **data)

Bases: pydantic.BaseModel

Memory entry for memory-aware RAG systems.

Represents a single memory entry with content, type, and metadata for use in conversation-aware RAG agents.

Parameters:

data (Any)

content

Memory content or summary.

Type:

str

memory_type

Type of memory (short-term, long-term, etc.).

Type:

MemoryType

timestamp

When this memory was created.

Type:

str

relevance_score

Relevance to current query (0.0 to 1.0).

Type:

float

context_tags

Tags for categorizing memory content.

Type:

List[str]

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.

class agents.rag.models.MemoryType

Bases: str, enum.Enum

Types of memory for memory-aware RAG.

SHORT_TERM

Short-term conversational memory.

LONG_TERM

Long-term knowledge memory.

EPISODIC

Episodic interaction memory.

SEMANTIC

Semantic knowledge memory.

Initialize self. See help(type(self)) for accurate signature.

class agents.rag.models.MergedResult(/, **data)

Bases: pydantic.BaseModel

Final merged result from multiple branches or strategies.

Contains the final synthesized result after combining outputs from multiple RAG branches or strategies.

Parameters:

data (Any)

primary_answer

Primary synthesized answer.

Type:

str

supporting_evidence

Supporting evidence from branches.

Type:

List[str]

confidence_score

Overall confidence (0.0 to 1.0).

Type:

float

sources_used

Sources used in the final answer.

Type:

List[str]

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.

class agents.rag.models.QueryClassification(/, **data)

Bases: pydantic.BaseModel

Query classification result for routing decisions.

Contains classification results used for routing queries to appropriate RAG strategies or processing branches.

Parameters:

data (Any)

primary_type

Primary query type.

Type:

QueryType

secondary_type

Secondary type if applicable.

Type:

Optional[QueryType]

complexity

Query complexity level.

Type:

str

confidence

Classification confidence (0.0 to 1.0).

Type:

float

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.

class agents.rag.models.QueryPlan(/, **data)

Bases: pydantic.BaseModel

Query planning result for complex query decomposition.

Contains a plan for executing a complex query, including sub-queries and execution strategy.

Parameters:

data (Any)

sub_queries

Sub-queries to execute.

Type:

List[str]

execution_strategy

How to execute them.

Type:

str

synthesis_approach

How to combine results.

Type:

str

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.

class agents.rag.models.QueryType

Bases: str, enum.Enum

Types of queries for branched RAG routing.

FACTUAL

Factual information queries.

ANALYTICAL

Analysis and reasoning queries.

CREATIVE

Creative and ideation queries.

PROCEDURAL

Step-by-step procedure queries.

Initialize self. See help(type(self)) for accurate signature.

class agents.rag.models.RAGModuleType

Bases: str, enum.Enum

Types of RAG modules for modular composition.

QUERY_EXPANSION

Query expansion and refinement module.

DOCUMENT_FILTERING

Document relevance filtering module.

CONTEXT_RANKING

Context relevance ranking module.

ANSWER_GENERATION

Answer generation module.

ANSWER_VERIFICATION

Answer quality verification module.

RESPONSE_SYNTHESIS

Final response synthesis module.

Initialize self. See help(type(self)) for accurate signature.

class agents.rag.models.ReActStep

Bases: str, enum.Enum

ReAct pattern step types.

THOUGHT

Reasoning and planning step.

ACTION

Action execution step.

OBSERVATION

Observation and analysis step.

REFLECTION

Reflection and evaluation step.

Initialize self. See help(type(self)) for accurate signature.

class agents.rag.models.ReActStepResult(/, **data)

Bases: pydantic.BaseModel

Result from a single ReAct pattern step.

Contains the output and metadata from executing a step in the ReAct (Reasoning + Acting) pattern.

Parameters:

data (Any)

step_type

Type of step executed.

Type:

ReActStep

content

Content or result of the step.

Type:

str

confidence

Confidence in this step (0.0 to 1.0).

Type:

float

next_action

Next action to take, if any.

Type:

Optional[str]

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.

class agents.rag.models.SpeculativeResult(/, **data)

Bases: pydantic.BaseModel

Speculative reasoning result with hypothesis verification.

Contains hypotheses generated and verified during speculative RAG, where multiple potential answers are explored and validated.

Parameters:

data (Any)

hypotheses

Generated hypotheses for the query.

Type:

List[str]

verified_hypotheses

Hypotheses verified against evidence.

Type:

List[str]

final_answer

Answer based on verified hypotheses.

Type:

str

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.

class agents.rag.models.StepBackResult(/, **data)

Bases: pydantic.BaseModel

Step-back reasoning result for abstract thinking.

Contains results from step-back prompting where the agent first reasons about high-level concepts before specific answers.

Parameters:

data (Any)

abstract_question

High-level abstract question derived from the query.

Type:

str

abstract_answer

Answer to the abstract question.

Type:

str

specific_answer

Specific answer to the original query.

Type:

str

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.

class agents.rag.models.StrategyDecision(/, **data)

Bases: pydantic.BaseModel

Strategy selection decision for agentic routing.

Contains the decision made by an agentic router about which RAG strategy to use for a given query.

Parameters:

data (Any)

strategy

Selected RAG strategy name.

Type:

str

confidence

Confidence in strategy selection (0.0 to 1.0).

Type:

float

reasoning

Explanation for why this strategy was chosen.

Type:

str

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.

class agents.rag.models.SubQueryResult(/, **data)

Bases: pydantic.BaseModel

Result from executing a single sub-query.

Contains the result of executing one sub-query in a query planning pipeline.

Parameters:

data (Any)

query

The sub-query that was executed.

Type:

str

answer

Answer to the sub-query.

Type:

str

confidence

Confidence in this result (0.0 to 1.0).

Type:

float

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.