> ## 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. All four launch surfaces — `praisonai <agents.yaml>`, `praisonai serve`, `praisonai eval`, and Python (`praisonai.run` / `praisonai.arun`) — wire the built-in retrievers, readers and rerankers before the agent starts, so `retriever: fusion` (or any built-in name) resolves identically on every surface ([PR #5322](https://github.com/MervinPraison/PraisonAI/pull/5322)).
  </Step>
</Steps>

***

## How it wires up

The registration is single-sourced in `AgentsGenerator.__init__`, so every launch path fires it once before the agent starts — not just the Python entry point.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    P[🐍 praisonai.run / arun] --> Init
    F[💻 praisonai agents.yaml] --> Init
    S[🌐 praisonai serve] --> Init
    E[📊 praisonai eval] --> Init
    Init[⚙️ AgentsGenerator.__init__] --> Reg[register_default_adapters]
    Reg --> R[🔍 retrievers]
    Reg --> Rd[📖 readers]
    Reg --> Rk[🎯 rerankers]

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

    class P,F,S,E entry
    class Init,Reg process
    class R,Rd,Rk output
```

The call is **idempotent and thread-safe** — it runs once per process even under startup races. It is also **register-only-if-absent**: a custom adapter you already registered under a built-in name (e.g. a multi-tenant host's own `fusion`) is preserved, never overwritten.

***

## 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 generator auto-wires the built-in adapters from `AgentsGenerator.__init__`, so a name like `retriever: fusion` resolves without any `register_default_adapters()` call — on **every** launch surface (`praisonai <file.yaml>`, `praisonai serve`, `praisonai eval`, and Python `run`/`arun`), not just the Python entry point ([PR #5322](https://github.com/MervinPraison/PraisonAI/pull/5322)). You only call it yourself when using retriever/reranker classes directly from your own Python code.
  </Accordion>

  <Accordion title="Safe in multi-agent setups">
    The retriever and reranker registries are thread-safe. If you're running many agents in parallel (native threads, asyncio, or a worker pool), they all share the same registry safely — no external locks needed, and no duplicate singletons on startup races. Since PraisonAI [#5197](https://github.com/MervinPraison/PraisonAI/pull/5197).
  </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>


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