Skip to main content

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:
ParameterTypeDefaultDescription
vector_storeAnyRequiredVector store instance
embedding_fnCallableRequiredFunction to generate embeddings
top_kint10Default 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:
ParameterTypeDefaultDescription
vector_storeAnyRequiredVector store instance
embedding_fnCallableRequiredEmbedding function
llmAnyNoneLLM for query variations
num_queriesint3Number of query variations
top_kint10Results per query
rrf_kint60RRF 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:
ParameterTypeDefaultDescription
vector_storeAnyRequiredVector store instance
embedding_fnCallableRequiredEmbedding function
llmAnyNoneLLM for follow-up queries
max_depthint2Maximum recursion depth
top_kint10Results 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:
ParameterTypeDefaultDescription
vector_storeAnyRequiredVector store instance
embedding_fnCallableRequiredEmbedding function
top_kint10Results to return
max_gapint1Max 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 CaseRecommended Strategy
Simple factual queriesBasicRetriever
Complex multi-part questionsFusionRetriever
Hierarchical documentsRecursiveRetriever
Long document summarizationAutoMergeRetriever

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