> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/tuning/interpreting-results.md).

# Interpret results

Read a TuningPlan's expected metrics and decision trace, then verify them against real searches with stats() and explain=True.

Read a tuning result in two parts. First, *what did the tuner predict, and why?* — that lives in the [`TuningPlan`](https://docs.telys.ai/tuning/tuner-and-plan.md). Second, *did the applied configuration deliver?* — confirm that against real searches. Never trust the prediction alone.

## Read what the tuner predicted

### `plan.expected`

The `expected` dict is the tuner's forecast for the plan it chose. Typical keys:

| Key             | Meaning                                                 | How to read it                                                                                |
| --------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `p50`           | Predicted median query latency (ms).                    | Your typical case.                                                                            |
| `p95`           | Predicted 95th-percentile latency (ms).                 | Your tail — what interactive users feel.                                                      |
| `recall_at_k`   | Predicted recall at the search `top_k`.                 | Should be at or above `plan.target_recall`.                                                   |
| `fallback_rate` | Share of queries expected to fall back to exact search. | High values mean many partitions sit below `exact_crossover_rows` and are still brute-forced. |

```python
plan = col.tune(dry_run=True)
print(plan.target_recall)          # the goal, e.g. 0.98
print(plan.expected["recall_at_k"]) # the prediction, e.g. 0.981
print(plan.expected["p95"])         # e.g. 4.3 (ms)
print(plan.expected["fallback_rate"])
```

### `plan.decision_trace`

`decision_trace` is an ordered list of readable steps showing *how* the tuner reached the plan — the statistics it read, the constraints it honored, and the tradeoff it settled on. Read it top to bottom when a plan surprises you.

```python
for step in plan.decision_trace:
    print(step)
```

`plan.constraints` records the bounds the tuner had to respect (latency, recall, memory). If `expected` looks worse than you hoped, the constraints usually explain why.

## Verify against reality

Predictions come from a model. Confirm them on your machine, with your data.

{% stepper %}
{% step %}

#### Check the applied configuration

After [applying and saving](https://docs.telys.ai/tuning/apply-and-save.md), `stats()` reflects the live IVF and recall settings.

```python
stats = col.stats()
print(stats["external_ids"])   # rows the config was sized for
print(stats)                   # runtime stats after apply
```

{% endstep %}

{% step %}

#### Explain a real search

Pass `explain=True` to see how a query was served — how many cells were probed and whether it used the approximate path or the exact fallback.

```python
res = col.search_text("reset my password", top_k=10, explain=True)
print(res["ids"])
print(res["explain"])          # per-query trace of how the search ran
```

{% endstep %}

{% step %}

#### Spot-check recall against exact

Compare a tuned result to an exact search by asking for full recall on that one query. Overlap in the returned ids is your measured recall.

```python
tuned = col.search_text("reset my password", top_k=10)
exact = col.search_text("reset my password", top_k=10, target_recall=1.0)
overlap = len(set(tuned["ids"]) & set(exact["ids"])) / len(exact["ids"])
print(overlap)                 # 1.0 means the tuned search missed nothing here
```

{% endstep %}
{% endstepper %}

## Make sense of the numbers

* **Recall below target.** Measured overlap under `target_recall` means the tuner gave up more recall than you want. Re-run with a higher recall objective or raise `target_recall`; expect latency to rise with it.
* **Latency higher than `expected`.** Predictions assume warm indexes and representative queries. First queries after `apply_tuning` run colder; measure the steady state.
* **`fallback_rate` near 1.0.** Most partitions sit below `exact_crossover_rows` and are already searched exactly, so tuning has little to do. This usually means the collection is not yet big enough to need it.
* **`p95` far above `p50`.** A heavy tail usually points at a few very large partitions. A finer partition key (see [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md)) can flatten it.

{% hint style="info" %}
`RemoteCollection.search` supports `explain=True` but not `target_recall=`. Run the recall spot-check against a **local** collection, then deploy the saved settings behind a server.
{% endhint %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Inspect collection stats</strong></td><td>Read every field <code>stats()</code> returns.</td><td><a href="https://docs.telys.ai/working-with-data/inspect-stats.md">Inspect stats</a></td></tr><tr><td><strong>Search internals (IVF)</strong></td><td>What nprobe and the crossover actually do.</td><td><a href="https://docs.telys.ai/understand-telys/search-internals-ivf.md">Search internals</a></td></tr><tr><td><strong>Run a tuning pass</strong></td><td>Re-tune with different objectives.</td><td><a href="https://docs.telys.ai/tuning/running-a-pass.md">Run a pass</a></td></tr></tbody></table>
