> 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

A tuning pass asks the collection's tuner to inspect the data and emit a [`TuningPlan`](/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](/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("$TELYS_HOME/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="/pages/mF6vIx4U7cBS5NHpb70Y">/pages/mF6vIx4U7cBS5NHpb70Y</a></td></tr><tr><td><strong>Interpret tuning results</strong></td><td>Read <code>expected</code> and the decision trace.</td><td><a href="/pages/dVG4mjMMPwA41mVMfhqv">/pages/dVG4mjMMPwA41mVMfhqv</a></td></tr><tr><td><strong>Tuner &#x26; TuningPlan</strong></td><td>Every field the plan carries.</td><td><a href="/pages/NznoaOZPDT34Q6o79zU5">/pages/NznoaOZPDT34Q6o79zU5</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/tuning/running-a-pass.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.