Module cross_encoder 

Cross-encoder reranking for semantic search results.

This module provides pairwise query-document scoring for reranking candidate documents retrieved from an initial retrieval stage. Unlike bi-encoder models that score query and document independently, cross-encoders jointly score the (query, document) pair for higher precision.

Architecture

The pipeline is:

1. Initial retrieval (e.g., HNSW ANN search) yields CandidateDoc list with initial_score.
2. CrossEncoder::rerank scores each (query, doc) pair via the configured ScoringModel.
3. Results are sorted by cross_encoder_score and optionally min-max normalized.
4. RerankedDoc carries the original rank metadata and score_delta for analysis.

Scoring Models

• ScoringModel::DotProduct — raw inner product, fast, unnormalized.
• ScoringModel::Cosine — cosine similarity in [-1, 1], direction-sensitive.
• ScoringModel::BilinearForm — diagonal bilinear Σ w_i q_i d_i, learned weights.
• ScoringModel::Linear — dot(weights, q ⊙ d) + bias, affine combination.

Example

use ipfrs_semantic::cross_encoder::{
    CrossEncoder, CrossEncoderConfig, ScoringModel, CandidateDoc,
};
use std::collections::HashMap;

let config = CrossEncoderConfig {
    model: ScoringModel::Cosine,
    max_doc_length: 512,
    batch_size: 32,
    normalize_scores: true,
};
let mut encoder = CrossEncoder::new(config);

let query = vec![1.0, 0.0, 0.0];
let candidates = vec![
    CandidateDoc {
        doc_id: "doc_a".to_string(),
        embedding: vec![0.9, 0.1, 0.0],
        initial_score: 0.8,
        metadata: HashMap::new(),
    },
    CandidateDoc {
        doc_id: "doc_b".to_string(),
        embedding: vec![0.0, 1.0, 0.0],
        initial_score: 0.9,
        metadata: HashMap::new(),
    },
];

let reranked = encoder.rerank(&query, candidates);
// doc_a should now rank #1 because it aligns better with query [1,0,0]
assert_eq!(reranked[0].doc_id, "doc_a");

Structs

CandidateDoc

A candidate document produced by an upstream retrieval system.

CrossEncoder

Cross-encoder that jointly scores (query, document) pairs for reranking.

CrossEncoderConfig

Configuration for the CrossEncoder.

CrossEncoderStats

Aggregate statistics collected across all reranking calls.

RerankedDoc

A reranked document with updated score and rank metadata.

Enums

ScoringModel

Relevance scoring model used by the CrossEncoder.