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

# Smart Retrieval

> Hybrid search with keyword prefiltering, semantic search, and reranking

Give agents sharper answers from large knowledge bases by combining keyword matching, semantic search, and reranking.

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

agent = Agent(
    name="Research Agent",
    instructions="Answer from the knowledge base.",
    knowledge={"sources": ["docs/"], "retrieval_k": 10, "rerank": True},
)
response = agent.start("How does API authentication work?")
```

The user asks a question; hybrid retrieval and reranking surface the best knowledge snippets.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Query[User Query] --> Hybrid[Hybrid Search]
    Hybrid --> Keyword[Keyword Match]
    Hybrid --> Semantic[Semantic Search]
    Keyword --> Merge[Score Fusion]
    Semantic --> Merge
    Merge --> Rerank[Rerank]
    Rerank --> Context[Injected Context]
    Context --> Agent[Agent Answer]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Query,Agent agent
    class Hybrid,Keyword,Semantic,Merge,Rerank,Context tool
```

## How It Works

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

    User->>Agent: Request
    Agent->>SmartRetrieval: Process
    SmartRetrieval-->>Agent: Result
    Agent-->>User: Response
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Enable reranking on the agent's knowledge config:

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

    agent = Agent(
        name="Research Agent",
        instructions="Answer from the knowledge base.",
        knowledge={"sources": ["docs/"], "retrieval_k": 10, "rerank": True},
    )
    response = agent.start("How does API authentication work?")
    ```
  </Step>

  <Step title="With Configuration">
    Use `KnowledgeConfig` for chunking, vector store, and rerank model:

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

    agent = Agent(
        name="Research Agent",
        instructions="Answer from the knowledge base.",
        knowledge=KnowledgeConfig(
            sources=["docs/"],
            retrieval_k=10,
            rerank=True,
            rerank_model="cohere/rerank-english-v3.0",
        ),
    )
    response = agent.start("How does API authentication work?")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Smart Retrieval

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

| Stage               | What it does                           |
| ------------------- | -------------------------------------- |
| **Keyword search**  | Fast lexical matching (BM25-style)     |
| **Semantic search** | Embedding similarity over chunks       |
| **Score fusion**    | Combines keyword and semantic scores   |
| **Reranking**       | Re-scores top candidates for relevance |

Strategy selection scales with corpus size — see [Retrieval Strategies](/docs/features/retrieval-strategies).

***

## Advanced: SmartRetriever

For direct control over retrieval strategy and filters, use `SmartRetriever` with a `Knowledge` instance:

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

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

result = retriever.retrieve(
    query="API authentication method",
    strategy="reranked",
    top_k=5,
)

for chunk in result.chunks:
    print(chunk.get("text", "")[:100])
```

***

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai knowledge search "API authentication" --rerank --top-k 10
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Enable rerank for large corpora">
    Reranking adds latency but improves relevance once you have hundreds of chunks. Start with `rerank=True` when answers feel noisy.
  </Accordion>

  <Accordion title="Tune retrieval_k before reranking">
    Fetch more candidates (`retrieval_k=10–20`) so the reranker has enough to choose from, then let the agent inject the top results.
  </Accordion>

  <Accordion title="Use hybrid strategies at scale">
    For technical docs with exact terms, rely on automatic strategy selection — hybrid and reranked modes combine keyword and semantic signals.
  </Accordion>

  <Accordion title="Scope by user or agent">
    Pass `user_id` or `agent_id` to `SmartRetriever.retrieve()` when isolating knowledge per tenant or sub-agent.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Retrieval Strategies" icon="route" href="/docs/features/retrieval-strategies">
    Automatic strategy selection by corpus size
  </Card>

  <Card title="Retrieval Configuration" icon="magnifying-glass" href="/docs/features/retrieval">
    Configure retrieval behaviour on agents
  </Card>
</CardGroup>