Retrievers & Rerankers in YAML

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

Quick Start

Declare the retriever and reranker

# 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

Run it

praisonai agents.yaml

No Python setup. The register_default_adapters() call happens for you before the agent starts (PraisonAI 4.7.9+).

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

Choosing a reranker

From the CLI

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

praisonai knowledge query "How do I authenticate?" \
  --retrieval fusion \
  --reranker llm

See Knowledge CLI for the full flag reference.

Best Practices

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.

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.

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.

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.

Retrieval from Python

Configure retrieval from Python

Adapter registry

How the adapter registry works

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Retrievers & Rerankers in YAML

Quick Start

Retriever choices

Reranker choices

Choosing a retriever

Choosing a reranker

From the CLI

Best Practices

Retrieval from Python

Adapter registry

​Quick Start

​Retriever choices

​Reranker choices

​Choosing a retriever

​Choosing a reranker

​From the CLI

​Best Practices

​Related

Retrieval from Python

Adapter registry

Quick Start

Retriever choices

Reranker choices

Choosing a retriever

Choosing a reranker

From the CLI

Best Practices

Related