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

> Configure retrieval strategies for knowledge bases

Tune top-k, similarity thresholds, and reranking so retrieval quality matches your use case.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, KnowledgeConfig

agent = Agent(
    name="Researcher",
    instructions="Cite retrieved passages in every answer.",
    knowledge=KnowledgeConfig(sources=["docs/"], top_k=5, similarity_threshold=0.7),
)
agent.start("Summarise the security section of our handbook.")
```

The user submits a query; the agent pulls the best-matching passages before composing a reply.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Retrieval"
        U[📋 Query] --> A[🔍 Rank passages]
        A --> O[✅ Top matches]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class U input
    class A process
    class O output
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Retrieve the top matching passages with a similarity floor.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Knowledge

    knowledge = Knowledge(sources=["docs/"], top_k=5, similarity_threshold=0.7)
    ```
  </Step>

  <Step title="With Configuration">
    Switch to hybrid search to blend keyword and semantic scoring.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Knowledge

    knowledge = Knowledge(
        sources=["docs/"],
        retrieval_strategy="hybrid",
        keyword_weight=0.3,
        semantic_weight=0.7,
    )
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Knowledge

    User->>Agent: Submit query
    Agent->>Knowledge: Rank passages by strategy
    Knowledge-->>Agent: Top-k passages
    Agent-->>User: Answer citing the passages
```

***

## Basic Retrieval

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Knowledge

knowledge = Knowledge(
    sources=["docs/"],
    top_k=5,                    # Number of results
    similarity_threshold=0.7    # Minimum similarity
)
```

## Retrieval Strategies

### Similarity Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge = Knowledge(
    sources=["docs/"],
    retrieval_strategy="similarity",
    top_k=5
)
```

### MMR (Maximal Marginal Relevance)

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge = Knowledge(
    sources=["docs/"],
    retrieval_strategy="mmr",
    top_k=5,
    diversity=0.3  # Balance relevance vs diversity
)
```

### Hybrid Search

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge = Knowledge(
    sources=["docs/"],
    retrieval_strategy="hybrid",
    keyword_weight=0.3,
    semantic_weight=0.7
)
```

## Query Enhancement

Use QueryRewriterAgent for better retrieval:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Knowledge, QueryRewriterAgent

# Rewrite queries for better retrieval
rewriter = QueryRewriterAgent()

knowledge = Knowledge(sources=["docs/"])

agent = Agent(
    name="Assistant",
    knowledge=knowledge,
    query_rewriter=rewriter
)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Pick the strategy that matches the query type">
    Use `similarity` for semantic questions, `hybrid` when exact keywords matter, and `mmr` when you need diverse rather than near-duplicate passages.
  </Accordion>

  <Accordion title="Balance diversity with MMR">
    `diversity=0.3` trades a little relevance for broader coverage. Raise it when top results repeat the same point.
  </Accordion>

  <Accordion title="Rewrite vague queries before retrieval">
    `QueryRewriterAgent` reshapes short or ambiguous questions into retrieval-friendly form, improving recall without changing the user's intent.
  </Accordion>

  <Accordion title="Tune top_k and threshold together">
    A high `top_k` with a low `similarity_threshold` floods the context; a low `top_k` with a high threshold can starve it. Adjust both when tuning quality.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Knowledge Module" icon="code" href="/docs/sdk/praisonaiagents/knowledge/knowledge">
    Full API reference
  </Card>

  <Card title="QueryRewriterAgent" icon="wand-magic-sparkles" href="/docs/sdk/praisonaiagents/agent/query_rewriter_agent">
    Query optimisation
  </Card>
</CardGroup>