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

# Retrievers & Rerankers in YAML

> Pick a retrieval strategy and reranker from your agents.yaml — no Python setup

Declare a retriever and reranker by name in your agent YAML and PraisonAI wires them into the knowledge base for you.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    YAML[📝 agents.yaml] --> CLI[💻 praisonai]
    CLI --> Wire[⚙️ register_default_adapters auto-called]
    Wire --> Retriever[🔍 FusionRetriever]
    Wire --> Reranker[🎯 LLMReranker]
    Retriever --> Answer[✅ Answer]
    Reranker --> Answer

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

    class YAML,CLI input
    class Wire,Retriever,Reranker process
    class Answer output
```

## Quick Start

<Steps>
  <Step title="Declare the retriever and reranker">
    ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # agents.yaml
    framework: praisonai
    process: sequential
    topic: "Answer questions from the docs"

    agents:
      researcher:
        role: "Research assistant"
        goal: "Answer questions with the highest-quality retrieved passages"
        instructions: "Expert at finding the exact snippet a user needs."
        knowledge:
          sources: ["./docs/"]
          retriever: fusion       # basic | fusion | recursive | auto_merge | hybrid
          reranker: llm           # llm | cross_encoder | cohere
          retrieval_k: 20
    ```
  </Step>

  <Step title="Run it">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai agents.yaml
    ```

    No Python setup. The `register_default_adapters()` call happens for you before the agent starts (PraisonAI 4.7.9+).
  </Step>
</Steps>

***

## Retriever choices

| Name         | When to use                                                                      | Extra install |
| ------------ | -------------------------------------------------------------------------------- | ------------- |
| `basic`      | Default — simple vector similarity                                               | None          |
| `fusion`     | Multiple query variations, then RRF merge — better recall on ambiguous questions | None          |
| `recursive`  | Depth-limited chunk expansion — better for hierarchical content                  | None          |
| `auto_merge` | Merges adjacent chunks from the same document — better for long passages         | None          |
| `hybrid`     | Vector + keyword combined                                                        | None          |

## Reranker choices

| Name            | When to use                                    | Extra install                       |
| --------------- | ---------------------------------------------- | ----------------------------------- |
| `llm`           | Highest quality — an LLM scores each candidate | `OPENAI_API_KEY`                    |
| `cross_encoder` | Local neural reranker — no API cost            | `pip install sentence-transformers` |
| `cohere`        | Cohere's hosted rerank API                     | `COHERE_API_KEY`                    |

***

## Choosing a retriever

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{What kind of query?} -->|Simple factual| Basic[basic]
    Start -->|Ambiguous / paraphrased| Fusion[fusion]
    Start -->|Hierarchical docs<br/>book, spec, wiki| Recursive[recursive]
    Start -->|Long passages<br/>need context| Merge[auto_merge]
    Start -->|Mix of keywords + concepts| Hybrid[hybrid]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef opt fill:#10B981,stroke:#7C90A0,color:#fff

    class Start q
    class Basic,Fusion,Recursive,Merge,Hybrid opt
```

## Choosing a reranker

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start{Priority?} -->|Highest quality| LLM[llm]
    Start -->|Zero API cost| CE[cross_encoder]
    Start -->|Hosted rerank API| Cohere[cohere]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef opt fill:#10B981,stroke:#7C90A0,color:#fff

    class Start q
    class LLM,CE,Cohere opt
```

***

## From the CLI

Same names, one-off from the `praisonai knowledge query` sub-command:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai knowledge query "How do I authenticate?" \
  --retrieval fusion \
  --reranker llm
```

See [Knowledge CLI](/docs/cli/knowledge) for the full flag reference.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with basic, upgrade when recall is low">
    Use `basic` first — it needs no LLM calls or extra installs. Move to `fusion` only when ambiguous or paraphrased questions miss the right passage.
  </Accordion>

  <Accordion title="Retrieve wide, rerank narrow">
    Set `retrieval_k` higher than the number of passages you actually want, then let the reranker trim to the best few. A common pairing is `retrieval_k: 20` with an `llm` reranker returning the top 5.
  </Accordion>

  <Accordion title="Match the reranker to your cost budget">
    `cross_encoder` runs locally with no API cost; `llm` is highest quality but bills per candidate; `cohere` is a hosted API. Pick based on whether cost, quality, or zero-dependency matters most.
  </Accordion>

  <Accordion title="No Python setup needed from YAML">
    The wrapper entry points auto-wire the built-in adapters, so a name like `retriever: fusion` resolves without any `register_default_adapters()` call. You only call it yourself when using retriever/reranker classes directly from your own Python code.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Retrieval from Python" icon="magnifying-glass" href="/docs/rag/retrieval">
    Configure retrieval from Python
  </Card>

  <Card title="Adapter registry" icon="plug" href="/docs/sdk/praisonai/adapters">
    How the adapter registry works
  </Card>
</CardGroup>