Use case · Explain

Audit any candidate with a typed explanation

Explainer::explain returns a typed payload that decomposes the rank into a score breakdown, the dominant Greeks, the comparable candidates, and the assumptions trail. The same payload powers the human-facing UI in Spread Foundry and the auditor view in MeridianScope.

When to use it

• You need to justify why a candidate ranks where it does — for a user, an auditor, or a compliance trail.
• You want the dominant risk (which Greek) and the near-misses (comparables) alongside the score.
• You want the assumptions (IV source, model, fit quality) attached to the recommendation.

Example

use ferro_spread::{Explainer, Explanation, ScoreContribution};

let exp: Explanation = Explainer::explain(&candidate, &ranker)?;

// Score breakdown — per-metric contribution
for ScoreContribution { metric, contribution } in &exp.breakdown {
    // metric: EV / PoP / CapitalEfficiency / ...
    // contribution: signed f64 in score units
}

// Where the risk lives
let (top_greek, top_value) = exp.dominant_greek();

// Sibling candidates within Δrank <= 2
for sibling in &exp.comparables { /* … */ }

// Audit trail: IV source, model, surface FitQuality
let assumptions = &exp.assumptions;

The explanation payload

Notes

• The payload is tested to reconcile with the rank — see the conventions on audit guarantees.
• Black-box ranking is treated as a feature gap, not a feature: every ranked output can be explained.