agents.rag.speculative.agent

Speculative RAG Agents.

from typing import Any Implementation of speculative RAG with parallel hypothesis generation and verification. Uses structured output models for hypothesis planning and iterative refinement.

Classes

Hypothesis	Individual hypothesis with structured metadata.
HypothesisConfidence	Confidence levels for hypotheses.
HypothesisGeneratorAgent	Agent that generates multiple hypotheses for speculative reasoning.
ParallelVerificationAgent	Agent that performs parallel hypothesis verification.
SpeculativeExecutionPlan	Plan for executing speculative retrieval and verification.
SpeculativeRAGAgent	Complete Speculative RAG agent with parallel hypothesis processing.
SpeculativeResult	Results from speculative RAG processing.
VerificationStatus	Status of hypothesis verification.

Functions

create_speculative_rag_agent(documents[, llm_config, ...])	Create a Speculative RAG agent.
get_speculative_rag_io_schema()	Get I/O schema for Speculative RAG agents.

Module Contents

class agents.rag.speculative.agent.Hypothesis(/, **data)

Bases: pydantic.BaseModel

Individual hypothesis with structured metadata.

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)

class agents.rag.speculative.agent.HypothesisConfidence

Bases: str, enum.Enum

Confidence levels for hypotheses.

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

class agents.rag.speculative.agent.HypothesisGeneratorAgent(llm_config=None, num_hypotheses=5, hypothesis_diversity='high', **kwargs)

Bases: haive.agents.base.agent.Agent

Agent that generates multiple hypotheses for speculative reasoning.

Initialize hypothesis generator.

Parameters:

• llm_config (haive.core.models.llm.base.LLMConfig | None) – LLM configuration

• num_hypotheses (int) – Number of hypotheses to generate

• hypothesis_diversity (str) – Diversity level (“low”, “medium”, “high”)

• **kwargs – Additional agent arguments

build_graph()

Build hypothesis generation graph.

Return type:

haive.core.graph.state_graph.base_graph2.BaseGraph

class agents.rag.speculative.agent.ParallelVerificationAgent(documents, llm_config=None, verification_depth='thorough', **kwargs)

Bases: haive.agents.base.agent.Agent

Agent that performs parallel hypothesis verification.

Initialize parallel verifier.

Parameters:

• documents (list[langchain_core.documents.Document]) – Documents for evidence gathering

• llm_config (haive.core.models.llm.base.LLMConfig | None) – LLM configuration

• verification_depth (str) – Depth of verification (“basic”, “thorough”, “comprehensive”)

• **kwargs – Additional agent arguments

build_graph()

Build parallel verification graph.

Return type:

haive.core.graph.state_graph.base_graph2.BaseGraph

class agents.rag.speculative.agent.SpeculativeExecutionPlan(/, **data)

Bases: pydantic.BaseModel

Plan for executing speculative retrieval and verification.

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)

class agents.rag.speculative.agent.SpeculativeRAGAgent(config)

Bases: haive.agents.multi.base.SequentialAgent

Complete Speculative RAG agent with parallel hypothesis processing.

Init .

Parameters:

config (SequentialAgentConfig) – [TODO: Add description]

classmethod from_documents(documents, llm_config=None, num_hypotheses=5, verification_depth='thorough', **kwargs)

Create Speculative RAG agent from documents.

Parameters:

• documents (list[langchain_core.documents.Document]) – Documents to index

• llm_config (haive.core.models.llm.base.LLMConfig | None) – LLM configuration

• num_hypotheses (int) – Number of hypotheses to generate

• verification_depth (str) – Depth of verification process

• **kwargs – Additional arguments

Returns:

SpeculativeRAGAgent instance

class agents.rag.speculative.agent.SpeculativeResult(/, **data)

Bases: pydantic.BaseModel

Results from speculative RAG processing.

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)

class agents.rag.speculative.agent.VerificationStatus

Bases: str, enum.Enum

Status of hypothesis verification.

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

agents.rag.speculative.agent.create_speculative_rag_agent(documents, llm_config=None, speculation_mode='balanced', **kwargs)

Create a Speculative RAG agent.

Parameters:

• documents (list[langchain_core.documents.Document]) – Documents for retrieval

• llm_config (haive.core.models.llm.base.LLMConfig | None) – LLM configuration

• speculation_mode (str) – Mode (“conservative”, “balanced”, “aggressive”)

• **kwargs – Additional arguments

Returns:

Configured Speculative RAG agent

Return type:

SpeculativeRAGAgent

agents.rag.speculative.agent.get_speculative_rag_io_schema()

Get I/O schema for Speculative RAG agents.

Return type:

dict[str, list[str]]