ElBruno.Reranking 0.5.1

ElBruno.Reranking

Semantic reranking for .NET: Local-first ONNX, cloud-ready APIs, and extensible backends.

ElBruno.Reranking improves search result relevance through intelligent semantic reordering. It provides a unified interface for multiple reranking backends:

• BGE-Reranker (ONNX): Fast local reranking (~15ms, CPU)
• Claude API: High-precision cloud reranking (98%+ R@5, <1s)
• Ollama: Flexible local LLMs (free, offline)
• Custom: Bring your own reranker

Features

✨ Simple API — Single RerankAsync() method for all backends
⚡ Fast ONNX inference — BGE reranker: <100ms for 100 docs
🧠 Cloud-ready Claude backend — Leverage LLMs for high-precision reranking
🎯 Pluggable architecture — Extend with custom backends
🔄 Async/await throughout — Built for high-concurrency .NET applications
🛠️ Production-ready — Error handling, retry logic, timeouts

Installation

dotnet add package ElBruno.Reranking

Or via NuGet Package Manager:

Install-Package ElBruno.Reranking

Quick Start (3 minutes)

ONNX Backend (Local Reranking)

using ElBruno.Reranking;

// Documents to rerank
var documents = new[]
{
    "Machine learning is a subset of artificial intelligence.",
    "Deep learning uses neural networks with many layers.",
    "The weather is sunny today.",
    "Natural language processing enables text understanding.",
};

// Create reranker (requires BGE model file)
var reranker = new OnnxReranker("./models/bge-reranker-base.onnx");

// Rerank
var result = await reranker.RerankAsync(
    query: "What is machine learning?",
    documents: documents,
    options: new RerankOptions { TopK = 5 }
);

// Results
foreach (var score in result.Scores)
{
    Console.WriteLine($"Score: {score.Score:F3}, Text: {score.Item.Text}");
}

Output:

Score: 0.918, Text: Machine learning is a subset of artificial intelligence.
Score: 0.876, Text: Deep learning uses neural networks with many layers.
Score: 0.654, Text: Natural language processing enables text understanding.
Score: 0.142, Text: The weather is sunny today.

Claude Backend (Cloud Reranking)

using ElBruno.Reranking;

var documents = new[]
{
    "The capital of France is Paris.",
    "Paris is a city known for the Eiffel Tower.",
    "The capital of Germany is Berlin.",
};

// Create Claude reranker
var reranker = new ClaudeReranker(apiKey: Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY"));

// Rerank with explanation
var result = await reranker.RerankAsync(
    query: "What is the capital of France?",
    documents: documents,
    options: new RerankOptions { TopK = 3, EnableRetry = true }
);

foreach (var score in result.Scores)
{
    Console.WriteLine($"Score: {score.Score:F3}, Text: {score.Item.Text}");
}

Documentation

• Quickstart Guide — Step-by-step setup for all backends
• BGE-Reranker (ONNX) Guide — Local-first reranking
• Claude Backend Guide — API-based high-precision reranking
• Custom Reranker Guide — Extend with your own backend
• Performance Tuning Guide — Optimize for your workload
• Architecture Deep-Dive — System design and abstractions
• Performance Benchmarks — Real-world latency and throughput
• Cost Estimation — BGE vs Claude cost analysis
• Roadmap — Future backends and features

Performance Benchmarks

Full benchmarks in docs/benchmarks.md

Core Concepts

RerankItem (Input)

public class RerankItem
{
    public string? Id { get; set; }                          // Caller-provided ID
    public string Text { get; set; }                         // Content to rerank
    public Dictionary<string, object>? Metadata { get; set; } // Custom metadata
}

RerankScore (Output Item)

public class RerankScore
{
    public RerankItem Item { get; }                 // Original item
    public float Score { get; }                     // Relevance score [0.0, 1.0]
    public int Rank { get; }                        // 1-based rank (1 = highest)
    public string? Explanation { get; }             // Optional reasoning (Claude backend)
}

RerankResult (Output)

public class RerankResult
{
    public IReadOnlyList<RerankScore> Scores { get; }             // Sorted by score (highest first)
    public int TotalItems { get; }                                // Total reranked
    public string Query { get; }                                  // Query used for reranking
    public string BackendName { get; }                            // Backend that produced result
    public long ElapsedMilliseconds { get; }                      // Time taken
    public Dictionary<string, string>? Diagnostics { get; }       // Diagnostics info
}

RerankOptions (Configuration)

public class RerankOptions
{
    public int TopK { get; set; } = int.MaxValue;           // Return top-k only
    public double MinScore { get; set; } = 0.0;             // Filter by threshold
    public int TimeoutMs { get; set; } = 30000;             // Request timeout
    public bool EnableRetry { get; set; } = true;           // Retry transient errors
    public int MaxRetries { get; set; } = 3;                // Max retry attempts
}

When to Use Each Backend

Choose BGE (ONNX) if you need:

• ✅ Fast local reranking (<100ms)
• ✅ Offline operation (no API key)
• ✅ Lower cost (free inference)
• ✅ Privacy (data stays local)

Choose Claude API if you need:

• ✅ High precision (98%+ R@5)
• ✅ Complex semantic reasoning
• ✅ Explanations for rankings
• ✅ Handling complex queries

Choose Custom if you need:

• ✅ Proprietary models
• ✅ Ensemble reranking
• ✅ Domain-specific scoring

Common Use Cases

Search Result Reranking — Improve BM25 or Elasticsearch rankings

var search = await elasticsearch.SearchAsync(query);
var reranked = await reranker.RerankAsync(query, search.Documents);

RAG Pipeline Enhancement — Improve retrieval quality for LLM context

var retrieved = vectorDb.Search(query, k=50);  // Get many candidates
var refined = await reranker.RerankAsync(query, retrieved, new RerankOptions { TopK = 5 });
var context = refined.Scores.Select(s => s.Item.Text);

Content Ranking — Reorder recommendations by query relevance

var candidates = await db.GetCandidates();
var ranked = await reranker.RerankAsync(userQuery, candidates);

Error Handling

try
{
    var result = await reranker.RerankAsync(query, documents);
}
catch (ArgumentException ex)
{
    // Input validation error (empty query, too many documents)
    Console.WriteLine($"Invalid input: {ex.Message}");
}
catch (RerankerException ex)
{
    // Backend-specific error
    Console.WriteLine($"Reranker failed: {ex.ErrorCode} - {ex.Message}");
}

Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.

Author

ElBruno — AI/ML engineer passionate about semantic search and .NET

• 🌐 elbruno.com
• 🐦 @elbruno
• 💼 LinkedIn

Acknowledgments

• BGE Model — BAAI
• Claude API — Anthropic
• Ollama — ollama.ai