`tauopt.engine.strategies.base`#

Strategy protocol: one strategy owns the FULL suggest step at one altitude – model fit + acquisition construction + acquisition optimization. That altitude is what keeps per-component in-housing cheap later: replacing a strategy’s internals never touches the seam.

Module Contents#

Classes#

`SuggestionDraft`	`intent` is present exactly when the draft is an authorized-duplicate grant – the driver copies it onto the OpenSuggestion so grant identity survives into canonical state.
`SuggestTimings`	Mutable per-ask timing sink (bench instrumentation): wall-clock spent in GP hyperparameter fitting vs acquisition optimization, accumulated across every rung attempted in one ask (a rung that times out still spent the time). Measurement only, never identity – nothing here may feed a hash or a seed.
`CenterNote`	Mutable per-rung-attempt note of the center-in-bootstrap decision (branch + action + reason). Measurement/audit only, never identity – nothing here may feed a hash or a seed. `ask` installs a fresh note per rung attempt so a failed rung’s note can never describe the rung that answered.
`InternalsNote`	Mutable per-ASK internal-state note: completed GP fit records, per-rung-attempt work records, and the acq-invocation count, accumulated across every rung attempted in one ask (the SuggestTimings pattern – a failed rung’s fit is computation too). `current_rung` is a cursor the ask boundary advances before each rung attempt so recorders never need the rung name threaded through strategy signatures. Audit only, never identity – nothing here may feed a hash or a seed (same contract as CenterNote/SuggestTimings).
`DedupNote`	Mutable per-ask dedup repair counters (audit only, never identity – nothing here may feed a hash or a seed; same contract as CenterNote/SuggestTimings). Accumulated across every rung attempted in one ask.
`Strategy`	`requires` names the install extras a strategy needs (e.g. (“botorch”,)); the registry filters availability by what is actually importable.

Functions#

`collect_suggest_timings`	Install a fresh sink for one ask; strategies record into it via record_fit / record_acq. Context-local, so concurrent asks never cross-pollute.
`collect_center_note`	Install a fresh center-note sink for one rung attempt.
`record_center`	Record the center decision. No-op when no sink is installed.
`record_fit`	Wrap a GP hyperparameter fit. No-op when no sink is installed.
`collect_internals_note`	Install a fresh internals sink for one ask (both ask paths install it alongside the timing sink; context-local, concurrent asks never cross-pollute).
`internals_rung`	The ask boundary’s rung cursor, for recorders that tag by rung. “unknown” outside an ask (direct strategy calls in tests/tools).
`internals_installed`	True when an internals sink is installed. Callers building a fit record should gate the (read-only but nonzero-cost) extraction on this, so paths without a sink – tight-timebox product asks included – pay nothing between fit and acquisition.
`record_gp_fit`	Record one completed GP fit (a provenance.GpFitRecord). No-op when no sink is installed.
`record_work`	Record one rung attempt’s acquisition work shape (a provenance.WorkRecord). No-op when no sink is installed.
`mark_stage`	Advance the GP phase cursor (“fit” \| “fantasy” \| “acq” \| None) – the cursor names the phase a rung last entered, read at exception-capture time. No-op when no sink is installed.
`internals_stage`	The GP phase cursor (None outside an ask or before any GP phase).
`record_conditioning`	Record one noise-escalation retry (a provenance.ConditioningEvent). No-op when no sink is installed.
`record_acq_init_filter`	Record one armed finite-filter receipt (a provenance. AcqInitFilterRecord). No-op when no sink is installed.
`record_aggregation`	Record the duplicate-x aggregation shape (a provenance.AggregationRecord). First writer wins – the group mapping is a pure function of state, so every rung in one ask derives the identical record. No-op when no sink is installed.
`record_acq`	Wrap an acquisition-function optimization. No-op when no sink is installed. Also counts the invocation into the internals note (the work shape: per-slot fills vs one batched q-ask) when one is installed.
`collect_dedup_note`	Install a fresh dedup-note sink for one ask (boundary-installed).
`record_dedup`	Record a dedup repair event (‘collision’ \| ‘queue_fill’ \| ‘reoptimize’ \| ‘advance’). No-op when no sink is installed.

API#

class tauopt.engine.strategies.base.SuggestionDraft(/, **data: Any)#

Bases: pydantic.BaseModel

intent is present exactly when the draft is an authorized-duplicate grant – the driver copies it onto the OpenSuggestion so grant identity survives into canonical state.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config#: ‘ConfigDict(…)’

assignments: tauopt.engine.space.Assignments#: None

intent: tauopt.engine.state.IntentTag | None#: None

class tauopt.engine.strategies.base.SuggestTimings#

Mutable per-ask timing sink (bench instrumentation): wall-clock spent in GP hyperparameter fitting vs acquisition optimization, accumulated across every rung attempted in one ask (a rung that times out still spent the time). Measurement only, never identity – nothing here may feed a hash or a seed.

Initialization

tauopt.engine.strategies.base.collect_suggest_timings() → Iterator[tauopt.engine.strategies.base.SuggestTimings]#: Install a fresh sink for one ask; strategies record into it via record_fit / record_acq. Context-local, so concurrent asks never cross-pollute.

class tauopt.engine.strategies.base.CenterNote#

Mutable per-rung-attempt note of the center-in-bootstrap decision (branch + action + reason). Measurement/audit only, never identity – nothing here may feed a hash or a seed. ask installs a fresh note per rung attempt so a failed rung’s note can never describe the rung that answered.

Initialization

set(branch: int, action: str, reason: str | None = None) → None#: Overwrite all three decision fields for this rung attempt.

tauopt.engine.strategies.base.collect_center_note() → Iterator[tauopt.engine.strategies.base.CenterNote]#: Install a fresh center-note sink for one rung attempt.

tauopt.engine.strategies.base.record_center(branch: int, action: str, reason: str | None = None) → None#: Record the center decision. No-op when no sink is installed.

tauopt.engine.strategies.base.record_fit() → contextlib.AbstractContextManager[None]#: Wrap a GP hyperparameter fit. No-op when no sink is installed.

class tauopt.engine.strategies.base.InternalsNote#

Mutable per-ASK internal-state note: completed GP fit records, per-rung-attempt work records, and the acq-invocation count, accumulated across every rung attempted in one ask (the SuggestTimings pattern – a failed rung’s fit is computation too). current_rung is a cursor the ask boundary advances before each rung attempt so recorders never need the rung name threaded through strategy signatures. Audit only, never identity – nothing here may feed a hash or a seed (same contract as CenterNote/SuggestTimings).

GP-conditioning fields: current_stage is a phase cursor GP strategies advance at their fit/fantasy/acq boundaries (reset with the rung cursor); conditioning_events accumulates escalation-controller retries; aggregation holds the duplicate-x aggregation record (first writer wins – the mapping is state-derived, identical across rungs); fallback_attempts accumulates failed-rung evidence records (boundary-appended, ladder order).

Initialization

tauopt.engine.strategies.base.collect_internals_note() → Iterator[tauopt.engine.strategies.base.InternalsNote]#: Install a fresh internals sink for one ask (both ask paths install it alongside the timing sink; context-local, concurrent asks never cross-pollute).

tauopt.engine.strategies.base.internals_rung() → str#: The ask boundary’s rung cursor, for recorders that tag by rung. “unknown” outside an ask (direct strategy calls in tests/tools).

tauopt.engine.strategies.base.internals_installed() → bool#: True when an internals sink is installed. Callers building a fit record should gate the (read-only but nonzero-cost) extraction on this, so paths without a sink – tight-timebox product asks included – pay nothing between fit and acquisition.

tauopt.engine.strategies.base.record_gp_fit(record) → None#: Record one completed GP fit (a provenance.GpFitRecord). No-op when no sink is installed.

tauopt.engine.strategies.base.record_work(record) → None#: Record one rung attempt’s acquisition work shape (a provenance.WorkRecord). No-op when no sink is installed.

tauopt.engine.strategies.base.mark_stage(stage: str | None) → None#: Advance the GP phase cursor (“fit” | “fantasy” | “acq” | None) – the cursor names the phase a rung last entered, read at exception-capture time. No-op when no sink is installed.

tauopt.engine.strategies.base.internals_stage() → str | None#: The GP phase cursor (None outside an ask or before any GP phase).

tauopt.engine.strategies.base.record_conditioning(event) → None#: Record one noise-escalation retry (a provenance.ConditioningEvent). No-op when no sink is installed.

tauopt.engine.strategies.base.record_acq_init_filter(record) → None#: Record one armed finite-filter receipt (a provenance. AcqInitFilterRecord). No-op when no sink is installed.

tauopt.engine.strategies.base.record_aggregation(record) → None#: Record the duplicate-x aggregation shape (a provenance.AggregationRecord). First writer wins – the group mapping is a pure function of state, so every rung in one ask derives the identical record. No-op when no sink is installed.

tauopt.engine.strategies.base.record_acq() → contextlib.AbstractContextManager[None]#: Wrap an acquisition-function optimization. No-op when no sink is installed. Also counts the invocation into the internals note (the work shape: per-slot fills vs one batched q-ask) when one is installed.

exception tauopt.engine.strategies.base.TimeboxExceeded#

Bases: RuntimeError

A strategy overran its time budget – the robustness ladder catches this.

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception tauopt.engine.strategies.base.QueueUnsupported#

Bases: RuntimeError

A strategy that nominally exposes suggest_selected cannot supply a queue for THIS config/space combination (e.g. gp_ei’s mixed-alternating optimizer is a best-only API – no restart pool exists). Raised BEFORE any compute; the boundary falls back to the rung’s suggest_unique path with the fill recorded pass-through (a strategy that cannot supply a queue -> pass-through argmax, recorded).

Initialization

Initialize self. See help(type(self)) for accurate signature.

exception tauopt.engine.strategies.base.UniqueRepairExhausted(message: str, drafts: list[tauopt.engine.strategies.base.SuggestionDraft])#

Bases: RuntimeError

A strategy’s dedup repair path ran out inside its declared cap with slots still unfilled. Carries the unique drafts it DID fill – the boundary keeps them, extends the exclusion set, and descends the ladder for the remainder (P6 ladder descent with the exclusion set propagated).

Initialization

Initialize self. See help(type(self)) for accurate signature.

class tauopt.engine.strategies.base.DedupNote#

Mutable per-ask dedup repair counters (audit only, never identity – nothing here may feed a hash or a seed; same contract as CenterNote/SuggestTimings). Accumulated across every rung attempted in one ask.

Initialization

tauopt.engine.strategies.base.collect_dedup_note() → Iterator[tauopt.engine.strategies.base.DedupNote]#: Install a fresh dedup-note sink for one ask (boundary-installed).

tauopt.engine.strategies.base.record_dedup(event: str, count: int = 1) → None#: Record a dedup repair event (‘collision’ | ‘queue_fill’ | ‘reoptimize’ | ‘advance’). No-op when no sink is installed.

class tauopt.engine.strategies.base.Strategy#

Bases: typing.Protocol

requires names the install extras a strategy needs (e.g. (“botorch”,)); the registry filters availability by what is actually importable.

suggest must be a pure function of (state, cfg): same inputs => same drafts, across processes (pin P4). No global RNG state may leak in or out.

OPTIONAL capability (deliberately NOT in this Protocol so custom strategies stay conformant): suggest_unique(state, cfg, n, exclude) – return exactly n drafts whose canonical assignment keys avoid exclude and each other, repairing collisions per the strategy’s own documented repair path, or raise UniqueRepairExhausted carrying the partial fill. The boundary getattr-probes for it; strategies without it get boundary-verified plain suggest output (collisions => ladder descent). Same purity contract as suggest.

OPTIONAL declaration: accepted_params (a frozenset of the params keys the strategy reads). When present, the ask boundary refuses any other key on an explicit config as a caller error (400 through either driver, the strict config-boundary posture); absent, the keys are the strategy’s own and nothing is checked. Every built-in declares it (the registry mirrors the sets so the check imports no math).

OPTIONAL declaration: read_params(state, cfg) – the ONE place the strategy reads its params dict (the typed readers, their ranges, the two-writer and posture refusals), returning what suggest executes. When present, the ask boundary runs it BEFORE any rung – for the strategy the config names, or for the strategy the policy routes under "auto" or with no config (on the routed config, which carries the caller’s top-level flags) – and answers its ValueError as the caller’s 400 (an AskValidationError naming the strategy and the key – the value and the expected domain for a typed, range or enumerated refusal, the keys and the rule for a two-writer or posture conflict), so a mistyped value never reaches a served suggestion; absent, the values are the strategy’s own and the ladder sees the raise. Every built-in GP strategy declares it; random and sobol read no params.

name: str#: None

requires: tuple[str, ...]#: None

suggest(state: tauopt.engine.state.ExperimentState, cfg: tauopt.engine.config.OptimizerConfig, n: int = 1) → list[tauopt.engine.strategies.base.SuggestionDraft]#

Return exactly n drafts as a pure function of (state, cfg) (pin P4).

A raise (TimeboxExceeded, a state the rung cannot model, a math failure) is the ask boundary’s signal to descend the never-fail ladder (pin P6); a bad-config ValueError from read_params never reaches here for the intended strategy – the boundary refused it first.

tauopt.engine.strategies.base#

Module Contents#

Classes#

Functions#

API#

`tauopt.engine.strategies.base`#