rerankers.md

# Optional rerankers

The default `none` provider returns original candidate order with `rerank_requested=false` and `rerank_applied=false`. Enabling, disabling or changing rerank only changes runtime configuration. Existing document vectors and original files are untouched.

`create_reranker(config, runtime_dir)` returns a provider with `rerank(query, candidates, top_n)`, `healthcheck()` and `provider_info()`. Candidate dictionaries retain their evidence/record IDs, original text, source locator and earlier scores. A successful result adds `scores.rerank` and stage/provider/score-direction metadata. Scores are ranking values, not calibrated probabilities.

All providers bound candidate count, query characters, document characters and concurrency. Defaults are 40 candidates, 4,000 query characters, 8,000 document characters and two concurrent calls. Truncation affects only the provider input; returned evidence text and citation positions remain original. `on_error=keep_candidates` preserves original top candidates with a machine-readable error and `rerank_applied=false`; `on_error=strict` raises `RerankerError`. Empty candidate lists do not call a service.

## SiliconFlow

The adapter implements JSON POST `/v1/rerank` with model, query, documents, top_n and `return_documents=false`; returned `results[].index` and `relevance_score` are validated. The official [SiliconFlow rerank API](https://docs.siliconflow.cn/docs/api/rerank-post) was checked on 2026-10-02. Model availability and pricing can change. There is no free-service promise, default model selection or live service verification in this repository.

Example runtime JSON:

```json
{
  "provider": "siliconflow",
  "endpoint": "https://api.siliconflow.cn/v1/rerank",
  "model": "BAAI/bge-reranker-v2-m3",
  "auth_env": "SILICONFLOW_API_KEY",
  "allow_remote_requests": true,
  "allowed_endpoints": ["https://api.siliconflow.cn/v1/rerank"],
  "timeout": 20,
  "retry": 2,
  "backoff": 0.25,
  "concurrency": 2,
  "max_documents": 40,
  "max_document_chars": 8000,
  "on_error": "keep_candidates"
}
```

Enabling remote rerank sends the question and bounded candidate book text to that exact endpoint. Consent and an exact endpoint allowlist are both required. An input manifest URL is not consent. Credentials come from the named environment variable; values are never stored in provider information, health diagnostics or failure messages. HTTPS is required. An explicit local HTTP exception exists only for localhost service testing. Redirects are blocked so credentials/body cannot follow to another address.

Timeout, 429, 503 and 504 retries are bounded by configured attempts. 401/403 are not retried. Backoff/Retry-After delays are capped at two seconds, response size is bounded, and error bodies are omitted to avoid credential echoes. Invalid, duplicate, bool or out-of-range indexes and nonfinite scores invalidate the whole response.

`healthcheck` is a passive configuration/credential check. `live_service_verified=false` makes clear that it does not call a billable endpoint. Tests use Mock HTTP responses and cover timeouts, HTTP errors, retries, response validation and candidate preservation; these are protocol tests, not online acceptance.

## Local CrossEncoder

The optional `local` adapter accepts an existing `model_path`, optional model label, `device` (default CPU), `batch_size` (default 8) and `max_length` (default 512 tokens). It uses Sentence Transformers CrossEncoder with `local_files_only=true`, `trust_remote_code=false` and `model_kwargs.use_safetensors=true`. Pickle-based model weight loading and model code downloads are not enabled. The [official CrossEncoder documentation](https://www.sbert.net/docs/package_reference/cross_encoder/model.html) documents local path/loading controls and forwarding model arguments; checked 2026-10-02.

```json
{
  "provider": "local",
  "model_path": "C:/Models/my-cross-encoder",
  "device": "cpu",
  "batch_size": 8,
  "max_length": 512,
  "on_error": "keep_candidates"
}
```

Install the optional local rerank dependencies separately. Provide a compatible Sentence Transformers/Hugging Face CrossEncoder directory with its tokenizer, configuration and safetensors weights. A directory offering only pickle-based weights fails explicitly. Arbitrary ONNX, GGUF or other model folders are not assumed compatible. Model cache is directed into runtime storage; large model files are not bundled or downloaded. Local loading failures are explicit. No local model weights were available for real inference acceptance; the suite tests constructor/inference contracts with a fake CrossEncoder and reports `model_inference_verified=false` in passive health output. Local inference runs synchronously under a provider lock; this release does not claim a hard kill timeout for native model execution.

## Custom protocol

`custom` accepts an approved HTTPS `endpoint`, safe nonsecret static headers, an `auth_env` reference with optional `auth_header`/`auth_scheme`, and constrained request/response mappings. JSON POST is the supported HTTP method. `protocol=siliconflow` selects the SiliconFlow compatible preset. `protocol=generic` requires explicit request and response mappings to adapt other object shapes.

```json
{
  "provider": "custom",
  "protocol": "generic",
  "endpoint": "https://rerank.example.com/order",
  "allow_remote_requests": true,
  "allowed_endpoints": ["https://rerank.example.com/order"],
  "auth_env": "CUSTOM_RERANK_KEY",
  "auth_header": "X-Api-Key",
  "auth_scheme": "",
  "request_mapping": {
    "input.question": "query",
    "input.passages": "documents",
    "count": "top_n"
  },
  "response_mapping": {
    "results": "data.items",
    "index": "document.position",
    "score": "value.score"
  },
  "higher_is_better": true
}
```

Request destinations and response fields use simple dotted object keys. Request sources are limited to query, documents, top_n, model and return_documents. No expressions, Python code, shell, templates or executable deserialization are accepted. The response must map each row back to the original zero based candidate index. Unsupported ID-only or non-JSON protocols require a dedicated adapter; they are not silently guessed.