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

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.

@dataclass
class RerankResult:
    text: str
    score: float
    original_index: int
    metadata: Dict[str, Any] = field(default_factory=dict)

RerankerProtocol

Protocol for reranker implementations.

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

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.

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

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

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

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)