> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.adapters import BasicRetriever, FusionRetriever
from praisonai.adapters.retrievers import RecursiveRetriever, AutoMergeRetriever
```

## Quick Example

<Note>
  Wrapper entry points (`praisonai.run`, `praisonai.arun`, and the `praisonai` CLI) call `register_default_adapters()` for you before the agent starts, so `retriever: fusion` (etc.) works from YAML/CLI without any Python setup. Call it explicitly only when using retriever classes directly from your own Python code (PraisonAI 4.7.9+). See [Registering the built-in adapters](/docs/docs/sdk/praisonai/adapters#registering-the-built-in-adapters).
</Note>

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/docs/sdk/praisonai/adapters#native-async-in-custom-retrievers-rerankers).

## Example: Fusion Retrieval with LLM

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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](/docs/sdk/praisonai/vector_store) - Store documents
* [Reranker Module](/docs/sdk/praisonai/reranker) - Rerank results
* [Readers Module](/docs/sdk/praisonai/readers) - Load documents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.