> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kettio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading confidence

> Deciding when a gap between two scores is a real difference.

Every ranked asset carries a `confidence` label and a `confidence_details` object. The label is
a summary; the details are what you should actually build logic against.

## The fields

| Field                    | What it measures                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| `entropy`                | Spread of the underlying response distribution. Higher means the persona was less decided. |
| `top_margin`             | Distance between the leading response bucket and the next one.                             |
| `sample_std_dev`         | Standard deviation across the three repetitions.                                           |
| `repetition_count`       | Repetitions behind the score (3).                                                          |
| `generator_sample_count` | Generator samples behind the score (6).                                                    |

`sample_std_dev` is the most directly useful of these. It tells you how much the pipeline
disagreed with *itself* on the same asset. A score whose repetitions ranged widely is a soft
score regardless of where it landed in the ordering.

## The 0.30 rule

Kettio treats any gap smaller than **0.30** as a close pair. That is the threshold at which
close-pair refinement is willing to run a pairwise panel, and it is a reasonable line for your
own logic too.

```javascript theme={null}
const CLOSE_PAIR_GAP = 0.30;

const [first, second] = ranked;
const gap = first.score - second.score;

if (gap < CLOSE_PAIR_GAP) {
  // Not a winner. Escalate or report both.
}
```

<Warning>
  A gap under 0.30 is **not a ranking**. Presenting rank 1 as the winner when it beat rank 2 by
  0.08 is presenting noise as a decision. Either escalate the pair to
  [`/api/v1/pairwise`](/guides/pairwise-api) or surface both as jointly leading.
</Warning>

## When refinement already ran

If you left `refine_close_pairs` at its default, Kettio has already done some of this for you.
It finds close pairs, sorts them by how close they are, and refines at most **6 pairs** per
request.

Check these fields before deciding whether you still need to escalate:

| Field                                           | Tells you                                                                    |
| ----------------------------------------------- | ---------------------------------------------------------------------------- |
| `score_before_refine`                           | The raw SSR score, prior to adjustment                                       |
| `panel_outcome`                                 | Non-null when a panel ran on this asset — includes whether the order flipped |
| `summary.close_pair_refinement.pairs_evaluated` | How many pairs were refined                                                  |

A `panel_outcome` showing a flip is informative: the SSR ordering and the pairwise panel
disagreed, and the panel won. A pair that was close but sat outside the top 6 was never
refined at all — the gap is still soft even though nothing in the response flags it.

## A usable decision rule

<Steps>
  <Step title="Reject the batch if assets failed">
    `summary.assets_failed > 0` means the ordering is incomplete.
  </Step>

  <Step title="Compare the top gap against 0.30">
    Above it, treat rank 1 as leading. Below it, treat the top assets as tied.
  </Step>

  <Step title="Sanity-check the spread">
    If `sample_std_dev` on either asset is large relative to the gap, the gap is inside the
    noise even if it clears 0.30.
  </Step>

  <Step title="Escalate ties rather than breaking them">
    Send the pair to the Pairwise API, or report both and let a human choose.
  </Step>
</Steps>

<Tip>
  The failure mode to design against is false precision. A ranking API will always return an
  order — including when the assets are indistinguishable. The confidence fields exist so your
  interface can say "these two are tied" instead of inventing a winner.
</Tip>