> 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/running-a-pass.md).

# Run a pass

Run col.tune() to produce a TuningPlan, and control whether the pass applies its result with the dry\_run flag.

A tuning pass asks the collection's tuner to inspect the data and emit a [`TuningPlan`](https://docs.telys.ai/tuning/tuner-and-plan.md). Run it with one call, `col.tune(...)`; the `dry_run` flag decides whether the pass also applies what it found.

## Before you start

* The signed runtime is installed and verified (`telys runtime install`, then `telys runtime verify`).
* The collection has a concrete tuner attached. The base `Tuner` raises `NotImplementedError`; use `HeuristicTuner` (bundled, runtime-only) or `AlgentaTuner` (from the `telys-algenta` adapter).
* A partition is large enough to matter — past roughly 20,000 live rows. See [Why tune](https://docs.telys.ai/tuning/why-tune.md).

{% hint style="info" %}
Attach the tuner at create time: `db.create_collection("notes", dim=384, partition_by="scope", tuner=HeuristicTuner())`. `open_collection` re-attaches the default `HeuristicTuner`, not a custom tuner you saved — so run `tune()` in the same session where you attached one.
{% endhint %}

## The signature

```python
col.tune(workload=None, objectives=None, dry_run=None) -> TuningPlan
```

| Parameter    | Type                      | Meaning                                                                                              |
| ------------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `workload`   | tuner-specific, or `None` | Representative queries the tuner fits to. `HeuristicTuner` ignores it; `AlgentaTuner` uses it.       |
| `objectives` | tuner-specific, or `None` | The recall / latency / memory goals the tuner should optimize toward. Shape is defined by the tuner. |
| `dry_run`    | `bool` or `None`          | Whether the pass applies its plan. See the table below.                                              |

### What `dry_run` does

| `dry_run`        | Behavior                                                                                           |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| `True`           | Compute a plan and **never** apply it. Nothing on the collection changes.                          |
| `False`          | Compute a plan and **always** apply it immediately.                                                |
| `None` (default) | Compute a plan; apply it **only if** `tuner.mode == "suggest_then_apply"`, otherwise suggest only. |

`col.tune(...)` always **returns** the `TuningPlan`, regardless of `dry_run`. The flag governs only whether the plan's settings are written onto the collection during the call.

## Run it

{% stepper %}
{% step %}

#### Open the collection and run a dry pass

Start with `dry_run=True` so you can read the plan before anything changes.

```python
from telys import Telys

db = Telys("./store")
col = db.open_collection("notes")

plan = col.tune(dry_run=True)   # compute only; apply nothing
```

{% endstep %}

{% step %}

#### Inspect the plan

```python
print(plan.plan_id)              # e.g. tune_9f2a1c
print(plan.tuner)                # e.g. heuristic
print(plan.target_recall)        # e.g. 0.98
print(plan.exact_crossover_rows) # e.g. 20000
print(plan.ivf)                  # chosen IVF layout
print(plan.expected)             # predicted p50/p95 ms, recall_at_k, fallback_rate
```

{% endstep %}

{% step %}

#### (Optional) fit to a workload

With `AlgentaTuner`, pass a sample of representative queries so the plan matches your access pattern.

```python
sample = ["reset my password", "cancel subscription", "export data"]
plan = col.tune(workload=sample, dry_run=True)
print(plan.workload_hash)   # non-empty once a workload is supplied
```

{% endstep %}
{% endstepper %}

## Expected result

`col.tune(dry_run=True)` returns a `TuningPlan` and changes nothing on disk or in the live collection. The printed fields look like:

```
tune_9f2a1c
heuristic
0.98
20000
{'nlist': 256, 'nprobe': 12}
{'p50': 1.8, 'p95': 4.3, 'recall_at_k': 0.981, 'fallback_rate': 0.004}
```

Exact numbers depend on your data, tuner, and hardware, but you always get a populated `TuningPlan`: a `plan_id`, a `target_recall`, an `exact_crossover_rows`, an `ivf` layout, and an `expected` metrics dict. Because this was a dry run, `col.stats()` is unchanged until you apply the plan.

{% hint style="warning" %}
If `col.tune()` raises `NotImplementedError`, the collection is using the base `Tuner`. Attach a concrete tuner (`HeuristicTuner` or `AlgentaTuner`). If importing `HeuristicTuner` raises `ImportError`, the runtime is not installed — run `telys runtime install`.
{% 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>Apply &#x26; save a plan</strong></td><td>Write the plan onto the collection and persist it.</td><td><a href="https://docs.telys.ai/tuning/apply-and-save.md">Apply &amp; save</a></td></tr><tr><td><strong>Interpret tuning results</strong></td><td>Read <code>expected</code> and the decision trace.</td><td><a href="https://docs.telys.ai/tuning/interpreting-results.md">Interpret results</a></td></tr><tr><td><strong>Tuner &#x26; TuningPlan</strong></td><td>Every field the plan carries.</td><td><a href="https://docs.telys.ai/tuning/tuner-and-plan.md">Tuner &amp; plans</a></td></tr></tbody></table>
