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

For retriever registry lookups, call register_default_adapters() once at startup — importing retriever classes no longer auto-registers them (PraisonAI 4.6.156+). See Registering the built-in adapters.

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 retrieval that offloads the blocking body via asyncio.to_thread(...), so calling it from an event loop no longer freezes it. Authors of custom retrievers on a natively-async provider should override aretrieve and await the native call directly — see Native async in custom retrievers / rerankers.

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

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

​Retrieval Module

​Import

​Quick Example

​Features

​Classes

​BasicRetriever

​FusionRetriever

​RecursiveRetriever

​AutoMergeRetriever

​Methods

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

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

​Example: Fusion Retrieval with LLM

​Strategy Selection Guide

​CLI Usage

​Related

Retrieval Module

Import

Quick Example

Features

Classes

`BasicRetriever`

`FusionRetriever`

`RecursiveRetriever`

`AutoMergeRetriever`

Methods

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

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

Example: Fusion Retrieval with LLM

Strategy Selection Guide

CLI Usage

Related