`tauopt.engine.config`#

Optimizer configs: the public, serializable, hashable unit of reproducibility.

The determinism contract (see AGENTS.md section Invariants): (engine_version, engine_sha, deps_fingerprint, config_hash, state, seed) => identical suggestion. Everything here is stdlib + pydantic.

Module Contents#

Classes#

`VarianceReplicationPolicy`	`variance_replication` intent kind: presence of this block ENABLES the kind; absent => no tokens of this kind, ever. `max_replicas` = the per-assignment replica cap.
`LiarVerificationPolicy`	`liar_verification` intent kind: presence enables; `max_verifications` = the per-source cap. The age floor theta_lie and near-incumbent window theta_top are fixed engine constants (engine._intents), not config knobs – only the caps are block fields.
`DuplicateIntents`	The per-kind enable blocks: each kind is DEFAULT DISABLED – an absent block means the boundary can never authorize that kind.
`QueueSelectionPolicy`	Temperature-annealed queue selection: presence of this block ENGAGES the selector; absent => selector-free behavior byte-exactly. `distance_weight` lambda = 0.0 is the temperature-only package (the distance term vanishes identically); `horizon` is the annealing budget – when unset BOTH DRIVERS inject the experiment’s declared `observation_budget`, and the engine falls back to the assumed 15 * dim (dim = the space’s parameter count; derived at ask time, never serialized – P8). The per-slot repair allowance is a fixed engine constant, deliberately not a knob (one number for “bounded re-optimize” everywhere it appears).
`OptimizerConfig`	Fully explicit strategy selection – the public config stratum.

Functions#

`blake2b_hex16`	16-hex-char blake2b digest (digest_size=8) of `payload`: the short content hash behind `config_hash` and the state/space hashes.
`stable_seed`	Deterministic seed from arbitrary parts via blake2b.
`resolve_seed`	Resolve the seed a strategy actually runs with – a pure function of its inputs.

API#

tauopt.engine.config.blake2b_hex16(payload: bytes) → str#: 16-hex-char blake2b digest (digest_size=8) of payload: the short content hash behind config_hash and the state/space hashes.

tauopt.engine.config.stable_seed(*parts: Any) → int#

Deterministic seed from arbitrary parts via blake2b.

NEVER Python’s builtin hash(): it is salted per process, which silently destroys cross-process reproducibility. Result fits in a non-negative int64 (torch.Generator.manual_seed range).

class tauopt.engine.config.VarianceReplicationPolicy(/, **data: Any)#

Bases: pydantic.BaseModel

variance_replication intent kind: presence of this block ENABLES the kind; absent => no tokens of this kind, ever. max_replicas = the per-assignment replica cap.

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(…)’

max_replicas: int#: 3

class tauopt.engine.config.LiarVerificationPolicy(/, **data: Any)#

Bases: pydantic.BaseModel

liar_verification intent kind: presence enables; max_verifications = the per-source cap. The age floor theta_lie and near-incumbent window theta_top are fixed engine constants (engine._intents), not config knobs – only the caps are block fields.

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(…)’

max_verifications: int#: 1

class tauopt.engine.config.DuplicateIntents(/, **data: Any)#

Bases: pydantic.BaseModel

The per-kind enable blocks: each kind is DEFAULT DISABLED – an absent block means the boundary can never authorize that kind.

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(…)’

variance_replication: tauopt.engine.config.VarianceReplicationPolicy | None#: None

liar_verification: tauopt.engine.config.LiarVerificationPolicy | None#: None

class tauopt.engine.config.QueueSelectionPolicy(/, **data: Any)#

Bases: pydantic.BaseModel

Temperature-annealed queue selection: presence of this block ENGAGES the selector; absent => selector-free behavior byte-exactly. distance_weight lambda = 0.0 is the temperature-only package (the distance term vanishes identically); horizon is the annealing budget – when unset BOTH DRIVERS inject the experiment’s declared observation_budget, and the engine falls back to the assumed 15 * dim (dim = the space’s parameter count; derived at ask time, never serialized – P8). The per-slot repair allowance is a fixed engine constant, deliberately not a knob (one number for “bounded re-optimize” everywhere it appears).

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(…)’

t_start: float#: 1.0

t_end: float#: 0.001

distance_weight: float#: 1.0

queue_cap: int#: 16

horizon: int | None#: None

class tauopt.engine.config.OptimizerConfig(/, **data: Any)#

Bases: pydantic.BaseModel

Fully explicit strategy selection – the public config stratum.

params is strategy-specific (each strategy documents its keys and defaults; a key the strategy does not read is refused at the ask). seed=None means “derive deterministically from (strategy, params, state)”; see :func:resolve_seed. strategy defaults to "auto", which routes via the default policy (like passing no config) while carrying the explicit top-level fields – the seedable policy path, and the form that makes config={"dedup": False} valid as typed; it takes no params. strategy is a v0 field, so it serializes at its default like seed and params ("strategy":"auto" stays in the canonical form; no hash moved when the default landed). Hosted users can pin any config; every served suggestion records the config that actually produced it (provenance).

center_in_bootstrap puts the domain center on the space-filling stream per a three-branch decision table (the branch taken is recorded in provenance). A top-level field, NOT a param: params feed :func:resolve_seed, and the flag must never move the scramble seed (branch-1 skips keep the exact unflagged stream). It rides the auto path and the fallback ladder like seed.

dedup (default True since 0.3.0) engages the suggest-time boundary: exact re-suggestion refused across observed union pending union the batch, strategy-owned repair, exhaustion proof, and the AskResult uniqueness surface. Explicit dedup: false is the per-config escape hatch (emission without the boundary; a non-default since 0.3.0, so its canonical form SERIALIZES – the hash moves). Top-level for the same reason as center_in_bootstrap: it must never move the underlying streams (the no-collision property requires flag-on == flag-off drafts byte-exactly). duplicate_intents enables the two authorized-duplicate kinds; it requires dedup (grants are authorizations THROUGH the dedup refusal – omission satisfies the requirement; explicit dedup: false still refuses). Both ride the auto path and the fallback ladder like seed.

queue_selection engages temperature-annealed selection over each slot’s already-budgeted candidate queue. It requires dedup (the candidate pipeline includes the dedup eligibility filter). Top-level like the flags above: it must never move the underlying generation streams (selection deviates AFTER generation; resolve_seed never sees top-level fields), and it rides the auto path and the fallback ladder.

categorical_mode selects gp_ei’s categorical GP embedding at the composable-flag surface, so the choice can ride auto (the params form cannot – auto refuses params). ONE fact, two writers: setting it here AND in params is refused at the consuming strategy. Top-level like the other flags – resolve_seed never sees it, so a seeded config’s streams are untouched; strategies that take no categorical embedding (sobol/random/ucb_cl rungs) carry it inert, and it rides the auto path and the fallback ladder like seed. None (the default, dropped from canonical form) preserves the exact prior bytes.

base_noise is the never-zero base observation-noise floor in RELATIVE (standardized) variance units – a fraction of observed y-variance, default 1e-3 (field band: SigOpt tikhonov seed 1e-3, hebo 8e-4, Vizier 3.9e-3; a 10x conditioning margin over the bare 1e-4 numerical floor). Explicit 0 opts out of the MECHANISM (the inferred constraint returns to the bare 1e-4 numerical floor; the fixed path un-floors) – never sigma^2=0 into the kernel, and duplicate-x aggregation plus the escalation controller stay armed. Strictly validated at config time: finite, >= 0, non-bool – inf/nan refuse loudly HERE, never surface as a rung failure. Never enters :func:resolve_seed (top-level fields never do – a leak would move sobol streams); 1e-3 drops from canonical form so every config predating this field keeps its exact bytes and config_hash (implicit default == explicit 1e-3; explicit 0 is a semantic non-default and hashes distinctly).

timebox_mode is the top-level form of the strategy-params key of the same name: "off" = wall-clock timebox OFF (algorithm-natural termination); "budget" = the explicit product default; "caps" = the third posture: off’s clock structure (no timeout machinery, TimeboxExceeded unreachable) with deterministic WORK ceilings (fit_maxiter/acq_maxiter params, version-pinned per-stratum defaults) – quality-under-budget. Top-level for the same reason as categorical_mode: the params form cannot ride auto (auto refuses params) and dies at the first fallback rung (rungs run with their own default params) – the envelope posture must survive both. "caps" is additionally TOP-LEVEL-ONLY (a params-form "caps" refuses with a pointer here): a params-form caps request that laddered on a real failure would silently resolve the fallback rung to default budget mode and re-enter wall coupling, defeating the mode’s contract. ONE fact, two writers: setting it here AND in params is refused at the consuming strategy (:func:~tauopt.engine.strategies._gp_common. effective_timebox), regardless of whether the values agree. It never feeds :func:resolve_seed; strategies without a wall budget (sobol/random rungs) carry it inert; None (the default, dropped from canonical form) preserves the exact prior bytes and hashes. One deliberate departure from the categorical_mode mirror: this field interacts with the deadline-injection classifier (_derive_rung_cfg) – a clean “off” under max_wait_s is neutralized to None on the EXECUTION copy while the injected budget pair rides in params (semantic identity untouched); categorical_mode has no injection analogue. "caps" under max_wait_s is NEVER injected over: the ask boundary enforces the deadline by cooperative rung-boundary refusal plus one post-completion delivery decision (AskDeadlineExceeded), so the executed rung stays clock-free. An explicit “budget” is a hash-visible synonym of the None default at execution time (the injection and resolve laws treat them identically).

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(…)’

strategy: str#: ‘auto’

params: dict[str, Any]#: ‘Field(…)’

seed: int | None#: None

center_in_bootstrap: bool#: False

dedup: bool#: True

duplicate_intents: tauopt.engine.config.DuplicateIntents | None#: None

queue_selection: tauopt.engine.config.QueueSelectionPolicy | None#: None

categorical_mode: Literal[one_hot, mixed, mixed_capped] | None#: None

timebox_mode: Literal[budget, off, caps] | None#: None

base_noise: float#: 0.001

canonical_json() → str#: Canonical minimal-form JSON of this config: sorted keys, compact separators, later-added top-level fields dropped at their defaults (P8), so older configs keep their exact bytes. This string is the exact payload :meth:config_hash digests. Raises ValueError when params contains a non-finite float (the finite-params re-verify).

config_hash() → str#: Content address of this config: blake2b_<16hex>, stable across processes.

tauopt.engine.config.resolve_seed(config: tauopt.engine.config.OptimizerConfig, state_hash: str, *, sequence_scope_hash: str) → int#

Resolve the seed a strategy actually runs with – a pure function of its inputs.

Explicit config.seed wins, verbatim.
Otherwise the seed derives from the strategy identity and the experiment state, so unseeded asks are still reproducible from a receipt (P4 holds either way). Sequence strategies (Sobol) derive from sequence_scope_hash (the space only) so their scramble stays FIXED across asks and the sequence genuinely continues; point strategies derive from state_hash so successive asks differ.

tauopt.engine.config#

Module Contents#

Classes#

Functions#

API#

`tauopt.engine.config`#