> ## 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

```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 version of retrieve (calls sync internally).

## 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