haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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 haive.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.