Retrieval Module

Document retrieval strategies with vector similarity and fusion

Retrieval Module

The Retrieval module provides concrete implementations of retrieval strategies for finding relevant documents from vector stores.

Import

from praisonai.adapters import BasicRetriever, FusionRetriever
from praisonai.adapters.retrievers import RecursiveRetriever, AutoMergeRetriever

Quick Example

from praisonai.adapters import BasicRetriever, ChromaVectorStore

# Create vector store and retriever
store = ChromaVectorStore(namespace="docs")
retriever = BasicRetriever(
    vector_store=store,
    embedding_fn=get_embedding,  # Your embedding function
    top_k=10
)

# Retrieve documents
results = retriever.retrieve("What is Python?", top_k=5)
for r in results:
    print(f"Score: {r.score:.3f} - {r.text[:50]}...")

Features

• Multiple retrieval strategies (Basic, Fusion, Recursive, AutoMerge)
• Reciprocal Rank Fusion for multi-query retrieval
• LLM-powered query expansion
• Recursive depth-limited retrieval
• Adjacent chunk merging for context

Classes

BasicRetriever

Simple vector similarity retrieval.

from praisonai.adapters import BasicRetriever

retriever = BasicRetriever(
    vector_store=store,
    embedding_fn=get_embedding,
    top_k=10
)
results = retriever.retrieve("search query")

Parameters:

Parameter	Type	Default	Description
vector_store	Any	Required	Vector store instance
embedding_fn	Callable	Required	Function to generate embeddings
top_k	int	10	Default number of results

FusionRetriever

Multi-query retrieval with Reciprocal Rank Fusion (RRF).

from praisonai.adapters import FusionRetriever

retriever = FusionRetriever(
    vector_store=store,
    embedding_fn=get_embedding,
    llm=agent,  # Optional: for query variation
    num_queries=3,
    top_k=10,
    rrf_k=60
)
results = retriever.retrieve("complex question")

Parameters:

Parameter	Type	Default	Description
vector_store	Any	Required	Vector store instance
embedding_fn	Callable	Required	Embedding function
llm	Any	None	LLM for query variations
num_queries	int	3	Number of query variations
top_k	int	10	Results per query
rrf_k	int	60	RRF constant

RecursiveRetriever

Depth-limited recursive retrieval with follow-up queries.

from praisonai.adapters.retrievers import RecursiveRetriever

retriever = RecursiveRetriever(
    vector_store=store,
    embedding_fn=get_embedding,
    llm=agent,  # For generating follow-up queries
    max_depth=2,
    top_k=10
)
results = retriever.retrieve("explain the architecture")

Parameters:

Parameter	Type	Default	Description
vector_store	Any	Required	Vector store instance
embedding_fn	Callable	Required	Embedding function
llm	Any	None	LLM for follow-up queries
max_depth	int	2	Maximum recursion depth
top_k	int	10	Results to return

AutoMergeRetriever

Retrieves and merges adjacent chunks from the same document.

from praisonai.adapters.retrievers import AutoMergeRetriever

retriever = AutoMergeRetriever(
    vector_store=store,
    embedding_fn=get_embedding,
    top_k=10,
    max_gap=1  # Max chunk gap for merging
)
results = retriever.retrieve("summarize the document")

Parameters:

Parameter	Type	Default	Description
vector_store	Any	Required	Vector store instance
embedding_fn	Callable	Required	Embedding function
top_k	int	10	Results to return
max_gap	int	1	Max gap between chunks to merge

Methods

retrieve(query, top_k=None, filter=None)

Retrieve documents matching the query.

Parameters:

• query (str): Search query
• top_k (int, optional): Override default result count
• filter (dict, optional): Metadata filter

Returns: List[RetrievalResult] - Matching documents with scores

aretrieve(query, top_k=None, filter=None)

Async version of retrieve (calls sync internally).

Example: Fusion Retrieval with LLM

from praisonai.adapters import FusionRetriever, ChromaVectorStore
from praisonaiagents import Agent

# Setup
store = ChromaVectorStore(namespace="knowledge")
agent = Agent(instructions="You help with search queries")

retriever = FusionRetriever(
    vector_store=store,
    embedding_fn=get_embedding,
    llm=agent,
    num_queries=3
)

# Query generates variations like:
# - "What is Python?"
# - "What is Python programming language?"
# - "Python definition"
results = retriever.retrieve("What is Python?", top_k=5)

Strategy Selection Guide

Use Case	Recommended Strategy
Simple factual queries	BasicRetriever
Complex multi-part questions	FusionRetriever
Hierarchical documents	RecursiveRetriever
Long document summarization	AutoMergeRetriever

CLI Usage

# Basic retrieval
praisonai knowledge query "What is Python?" --retrieval basic

# Fusion retrieval
praisonai knowledge query "Compare Python and Java" --retrieval fusion

# Recursive retrieval
praisonai knowledge query "Explain the architecture" --retrieval recursive

# Auto-merge retrieval
praisonai knowledge query "Summarize the document" --retrieval auto_merge

Related

• Vector Store Module - Store documents
• Reranker Module - Rerank results
• Readers Module - Load documents