[FEATURE] Add reranker fallback chains to statement reranking

[marora90]

Description

This PR adds ordered fallback chains for final statement reranking while keeping entity reranking unchanged.

Users can continue to configure a single reranker:

reranker='tfidf'

or provide an ordered chain:

reranker=['bedrock', 'tfidf']

If an earlier statement reranker raises and the fallback policy permits recovery, the next strategy is attempted.

Changes

• Accept an ordered list of final statement rerankers.
• Add reranker_fallback_policy, called as:

  policy(reranker, *, error=None) -> bool

• Support none as either:

  • the only strategy, disabling statement reranking; or
  • the final fallback, returning the original unreranked statements once reached.

• Validate list-based reranker chains.

• Improve fallback logging:

  • successful reranking logs at DEBUG;
  • fallback warnings name the failed and next strategies;
  • warnings retain the exception type and traceback;
  • empty score maps log at ERROR.

• Clarify the statement/entity reranking distinction in the public documentation.

• Make the throttling-policy example robust to exceptions whose response attribute is not a dictionary.

Problem

Model-based rerankers can fail because of transient provider errors such as throttling.

Previously, callers had to either accept that failure or implement fallback outside the retrieval pipeline.

This change allows callers to prefer a model-based reranker while retaining a local fallback.

Fallback remains stateless and is evaluated per query. A reranker that failed for one query will be attempted again for the next query.

Related issue: #403

Decisions to review

A few behaviors are intentional but worth confirming during review:

1. Reranker chains only apply to statements

reranker and reranker_fallback_policy control final statement reranking. Entity reranking remains independent and
always uses TF-IDF, even when statement reranking is disabled with None or none.

2. Fallback allows any exception by default

Without a custom policy, any failure from a non-final reranker advances to the next strategy. This includes transient
errors such as throttling, but also configuration, credential, dependency, or implementation errors.

A custom policy can restrict which failures allow fallback. Exceptions from the final reranker—and exceptions raised by
the policy itself—always propagate.

3. Falling back to none still requires policy approval

For ['bedrock', 'none'], the Bedrock failure must be approved by the fallback policy before none is reached. If
denied, the original exception propagates.

Once reached, none performs no scoring and cannot fail.

4. Empty score maps do not trigger fallback

An empty score map is treated as a completed scorer response. It is logged at ERROR, no fallback is attempted, and all
statements are dropped.

This preserves existing behavior, but is worth confirming because it may be surprising in a chain.

5. Existing validation behavior is preserved

ProcessorArgs remains permissive, with validation performed by RerankStatements. Lists validate reranker names and
the placement of none; legacy single-string values retain their existing, less-strict behavior for compatibility.

6. Fallback state is not remembered

Fallback is evaluated independently for every query. A failed provider is retried on the next query rather than being
temporarily disabled, so persistent failures may add latency until the underlying issue is resolved.

Testing

• Unit tests added/updated
• Integration tests added (as appropriate)
• Existing tests pass (pytest)
• Tested manually (describe below)

Checklist

• Code follows existing style and conventions
• License headers present on new files
• Documentation updated (if applicable)
• No breaking changes (or clearly documented)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.