> 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/reference/tuner-api.md).

# Tuner & plans

Reference for Tuner, TuningPlan, and the runtime-only HeuristicTuner — the objects that produce, describe, and apply a collection's index tuning.

Tuning turns a workload into a `TuningPlan` — a recall target, an exact-crossover threshold, and IVF parameters — that the collection applies and persists. `Tuner` and `TuningPlan` are top-level; `HeuristicTuner` comes from the signed runtime.

```python
from telys import Tuner, TuningPlan
```

## Tuner (base)

The base class defines the tuning interface; its `name` is `"base"`. `tune_collection` is abstract — subclasses (such as the runtime's `HeuristicTuner`) implement the policy.

| Signature                                                     | Returns      | Description                                                                      |
| ------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------- |
| `tune_collection(collection, workload=None, objectives=None)` | `TuningPlan` | Build a plan for the collection. Raises `NotImplementedError` on the base class. |
| `choose_plan(stats, query)`                                   | plan         | Select a plan given current stats and a query.                                   |
| `explain()`                                                   | —            | Human-readable description of the tuner's policy.                                |

Don't call a tuner directly. Attach one at creation, then call `Collection.tune()`:

```python
from telys import Telys

ame = Telys("./memory")
col = ame.create_collection("notes", dim=384, partition_by="scope", tuner=my_tuner)
plan = col.tune(workload=my_workload)   # delegates to the tuner
```

## TuningPlan

A dataclass describing a tuning decision. It is the return value of `Collection.tune()` and the argument to `Collection.apply_tuning()`.

| Field                  | Default    | Meaning                                                   |
| ---------------------- | ---------- | --------------------------------------------------------- |
| `collection`           | (required) | Name of the target collection.                            |
| `tuner`                | (required) | Name of the tuner that produced the plan.                 |
| `target_recall`        | (required) | Desired recall for approximate search.                    |
| `exact_crossover_rows` | (required) | Row count below which exact search is used.               |
| `ivf`                  | (required) | IVF parameters as a `dict` (e.g. lists/nprobe).           |
| `expected`             | (required) | Expected outcomes (latency/recall estimates) as a `dict`. |
| `constraints`          | (required) | Constraints considered, as a `dict`.                      |
| `decision_trace`       | (required) | `list` of the decisions taken.                            |
| `workload_hash`        | `""`       | Hash of the workload the plan was built for.              |
| `engine`               | `"telys"`  | Engine that produced the plan.                            |
| `plan_id`              | `""`       | Auto-assigned `tune_<hash>` when empty.                   |

Methods:

| Method          | Returns | Description                                     |
| --------------- | ------- | ----------------------------------------------- |
| `as_dict()`     | `dict`  | Serializable form of the plan.                  |
| `to_json(**kw)` | `str`   | JSON string (`**kw` forwarded to `json.dumps`). |

```python
plan = col.tune(dry_run=True)     # build but never apply
print(plan.plan_id, plan.target_recall, plan.exact_crossover_rows)
print(plan.to_json(indent=2))
```

{% hint style="info" %}
There is **no** `TuningPlan.save`. A plan is applied with `Collection.apply_tuning(plan)`, then persisted by `Collection.save()`, which stores `default_target_recall` and `applied_tuner`.
{% endhint %}

## Applying a plan

`Collection.tune()` optionally applies as it goes; `Collection.apply_tuning()` applies an existing plan.

| Signature                                                       | Returns      | Description                                                                                                          |
| --------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------- |
| `Collection.tune(workload=None, objectives=None, dry_run=None)` | `TuningPlan` | `dry_run=True` never applies; `False` always applies; `None` applies only when `tuner.mode == "suggest_then_apply"`. |
| `Collection.apply_tuning(plan)`                                 | `stats`      | Sets `default_target_recall` and exact-crossover, builds/uses per-partition IVF, and sets `nprobe`.                  |

```python
plan = col.tune(dry_run=True)
stats = col.apply_tuning(plan)   # apply the reviewed plan
col.save()                       # persist default_target_recall + applied_tuner
```

## HeuristicTuner (runtime-only)

`HeuristicTuner` is listed in `telys.__all__` but is **not** implemented in the thin SDK. It resolves lazily from the signed runtime and raises `ImportError` when the runtime is not installed.

```python
from telys import HeuristicTuner   # ImportError without the runtime
```

{% hint style="warning" %}
Install and verify the runtime (`telys runtime verify`) before relying on any tuner beyond the base class.
{% endhint %}

## See also

<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>Why tune</strong></td><td>What tuning trades off and when to bother.</td><td><a href="https://docs.telys.ai/tuning/why-tune.md">Why tune</a></td></tr><tr><td><strong>Run a tuning pass</strong></td><td>Produce a plan from a workload.</td><td><a href="https://docs.telys.ai/tuning/running-a-pass.md">Run a pass</a></td></tr><tr><td><strong>Apply &#x26; save a plan</strong></td><td>Apply and persist a reviewed plan.</td><td><a href="https://docs.telys.ai/tuning/apply-and-save.md">Apply &amp; save</a></td></tr><tr><td><strong>Search internals (IVF)</strong></td><td>What nprobe and exact-crossover mean.</td><td><a href="https://docs.telys.ai/understand-telys/search-internals-ivf.md">Search internals</a></td></tr></tbody></table>
