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

# Rerankers Module

> Document reranking with LLM, cross-encoder, and keyword-based methods

# Rerankers Module

The rerankers module provides methods to reorder retrieved documents by relevance to the query.

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.knowledge.rerankers import (
    RerankResult,
    RerankerProtocol,
    RerankerRegistry,
    get_reranker_registry,
    SimpleReranker
)

# Use built-in simple reranker (no external deps)
reranker = SimpleReranker()

results = reranker.rerank(
    query="Python programming",
    documents=["Python tutorial", "Java guide", "Python best practices"],
    top_k=2
)

for result in results:
    print(f"{result.text} (score: {result.score})")
```

## Reranker Types

| Type            | Description                 | Dependencies          |
| --------------- | --------------------------- | --------------------- |
| `simple`        | Keyword-based scoring       | None (built-in)       |
| `llm`           | LLM-based relevance scoring | OpenAI/Anthropic      |
| `cross_encoder` | Cross-encoder model         | sentence-transformers |
| `cohere`        | Cohere Rerank API           | cohere                |

## Classes

### RerankResult

Dataclass for reranking results.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@dataclass
class RerankResult:
    text: str
    score: float
    original_index: int
    metadata: Dict[str, Any] = field(default_factory=dict)
```

### RerankerProtocol

Protocol for reranker implementations.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
class RerankerProtocol(Protocol):
    name: str
    
    def rerank(
        self,
        query: str,
        documents: List[str],
        top_k: Optional[int] = None,
        **kwargs
    ) -> List[RerankResult]:
        """Rerank documents by relevance to query."""
        ...
```

### SimpleReranker

Built-in keyword-based reranker (no external dependencies).

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.knowledge.rerankers import SimpleReranker

reranker = SimpleReranker()

results = reranker.rerank(
    query="machine learning",
    documents=[
        "Deep learning tutorial",
        "Cooking recipes",
        "Machine learning basics"
    ],
    top_k=2
)
# Returns: ["Machine learning basics", "Deep learning tutorial"]
```

### RerankerRegistry

Registry for managing reranker implementations.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.knowledge.rerankers import get_reranker_registry

registry = get_reranker_registry()

# List available rerankers
rerankers = registry.list_rerankers()  # ['simple', 'llm', ...]

# Get reranker by name
reranker = registry.get("simple")

# Register custom reranker
registry.register("custom", MyReranker)
```

## Using with Knowledge

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

# Configure reranker
agent = Agent(
    instructions="You are a helpful assistant",
        knowledge={
        "sources": ["docs/"],
        "reranker": "simple",  # or "llm", "cross_encoder", "cohere"
        "rerank_top_k": 5
    }
        "reranker": "simple",  # or "llm", "cross_encoder", "cohere"
        "rerank_top_k": 5
    }
)

response = agent.chat("What is the best approach?")
```

## Creating Custom Rerankers

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.knowledge.rerankers import (
    RerankResult,
    get_reranker_registry
)
from typing import List, Optional

class MyReranker:
    name = "my_reranker"
    
    def rerank(
        self,
        query: str,
        documents: List[str],
        top_k: Optional[int] = None,
        **kwargs
    ) -> List[RerankResult]:
        # Custom scoring logic
        scored = []
        for i, doc in enumerate(documents):
            score = self._compute_score(query, doc)
            scored.append(RerankResult(
                text=doc,
                score=score,
                original_index=i
            ))
        
        # Sort by score descending
        scored.sort(key=lambda x: x.score, reverse=True)
        
        if top_k:
            scored = scored[:top_k]
        
        return scored
    
    def _compute_score(self, query: str, doc: str) -> float:
        # Your scoring logic
        ...

# Register
registry = get_reranker_registry()
registry.register("my_reranker", MyReranker)
```

## LLM Reranker Example

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.knowledge.rerankers import get_reranker_registry

# Get LLM reranker (requires OpenAI API key)
registry = get_reranker_registry()
llm_reranker = registry.get("llm", model="gpt-4o-mini")

results = llm_reranker.rerank(
    query="How to deploy to production?",
    documents=documents,
    top_k=5
)
```

## Performance

* **SimpleReranker** is pure Python with no dependencies
* LLM reranker makes API calls (latency depends on provider)
* Cross-encoder requires sentence-transformers (loaded lazily)