> 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 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 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_` 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
Why tuneWhat tuning trades off and when to bother./pages/dUb8SpYWDKmPq4apsKnQ
Run a tuning passProduce a plan from a workload./pages/oRgOGxUrNbTlcSvpJeau
Apply & save a planApply and persist a reviewed plan./pages/mF6vIx4U7cBS5NHpb70Y
Search internals (IVF)What nprobe and exact-crossover mean./pages/34ekyTEaG3dG24136d0C
--- # 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/reference/tuner-api.md?ask=&goal= ``` `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.