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

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

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

RerankerProtocol

Protocol for reranker implementations.

python

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

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

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

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

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)

Thread Safety

RerankerRegistry is a thread-safe singleton — register, get, list_rerankers, and clear are all guarded by an internal lock, and concurrent get_reranker_registry() calls always return the same instance.

LLM Reranker Example

python

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)
RerankerRegistry operations acquire a lightweight lock — negligible overhead in single-threaded use, no KeyError or iteration errors under concurrent register/clear