tauopt.models

Pydantic mirrors of the /v1 API objects – what both drivers hand back to callers.

Featherweight: pydantic only. Shapes are SigOpt-lineage; Suggestion carries the engine provenance that re-derives it. The space language spans categorical/grid/conditions + linear constraints; the metrics cluster spans multimetric/thresholds/stored + num_solutions; observations can carry noise.

Module Contents

Classes

Page	One page of a list route (Client.suggestions, Client.observations): the list every caller iterates, indexes and measures, plus total – the TOTAL number of rows under the call’s filters (the service’s count; the page’s own length on the all-rows path), so a paging caller knows when it has read the last page. The attribute is total, not count, so count(value) stays the list method. copy(), copy.copy, copy.deepcopy and pickling keep total; a slice (page[1:]), a concatenation (page + rows) and a repetition (page * n) are plain lists without it, and an in-place += or extend keeps the old total. == compares the rows only: a page equals a plain list of the same rows, and two pages with different totals and the same rows are equal.
Metric	One experiment metric: objective sets the direction, strategy the role (optimized, stored-only, or an outcome constraint), and threshold the constraint/frontier bound.
ParameterSpec	One search-space parameter: numeric (double/integer) with exactly one of bounds or an explicit grid, or categorical with categorical_values. conditions makes it active only when each named parent categorical takes one of the listed values.
LinearConstraintSpec	One linear constraint over plain double parameters: the terms coefficient-weighted sum op rhs. Suggestions satisfy every linear constraint by construction.
ProvenanceTimings	Wall-clock split of the suggest step: GP fit vs acquisition-optimization seconds across the ask. Absent on instant rungs (random/sobol).
CenterRecord	Mirror of the engine’s center-in-bootstrap decision record (branch / action / reason).
Provenance	Mirror of the engine’s provenance receipt (identity triple).
BestObservation	One entry of best_assignments: value in single-metric mode, values for multimetric (frontier entries).
Progress	Experiment progress snapshot: observation_count, the scalar best_observation, expected_suggest_s (the next ask’s cost estimate; populated by the hosted plane, None from the local driver), open_suggestions (the open-suggestion count, both drivers), and frontier_count (the size of the non-dominated frontier of a multimetric experiment, the hosted plane’s bounded count: None on single-metric experiments, from the local driver, and past the service’s listing bound). The scalar best is None until a non-failed observation exists, and always None for multimetric experiments (the frontier is read via best assignments instead).
Experiment	An optimization experiment: the search space (parameters plus optional linear_constraints), the metric cluster (metric, or metrics when multimetric), and run settings (observation_budget, parallel_bandwidth, num_solutions).
Suggestion	One suggested trial: the assignments to evaluate next, plus the provenance receipt identifying exactly how it was derived (replay additionally needs the recorded experiment state). state flips to closed when an observation reports against it, when it is explicitly dismissed, or (hosted plane only) when the next ask finds it older than the experiment’s suggestion_ttl_s and sets expired_at.
Observation	One reported result for a set of assignments: value or per-metric values, optional noise via value_stddev/values_stddev, or failed=True for a failed evaluation. suggestion_id is None when the observation is reported off-suggestion (direct assignments).
BestAssignments	200-with-empty-data when nothing succeeded yet – the answer is an empty set, not a broken service. Multimetric: the Pareto frontier. num_solutions > 1: the diverse top-k.
ExperimentList	One page of GET /v1/experiments: count is the total under the call’s filters (by default the caller’s ACTIVE experiment total – the number the active-experiment cap counts – not the page size) and data the page, newest first by default, each row WITH its progress (the hosted list leaves expected_suggest_s null; read one by id for the estimate). Archived experiments are listed only with include_deleted; read one by id.
Health	GET /health: status is "ok" after the service’s database round-trip (no token needed, so it says nothing about yours); the local driver answers "ok" for the in-process engine.
AuthCheck	GET /v1/auth/check: user_id is the account the token resolves to (an integer from the hosted service; the request is not counted as usage). The local driver has no accounts and answers None.

Functions

metric_shorthand_message

The 400 validation_error message both drivers answer to a bare-string metric="<name>": the shorthand names no objective, and the old expansion to {"name": name} maximized a loss silently. One text, quoted by TROUBLESHOOTING.md, built here so the Client’s pre-flight and the local driver’s door never drift.

body_defect

The service’s body-defect gate, mirrored (app/api/validation.py body_defect): the first defect in a parsed body value – dict keys included, containers walked – or None: a string with a NUL, a string no UTF-8 encoder can carry (a lone surrogate), a non-finite float (bool is not float). The gate runs before any field parses, so on the hosted plane a defect inside a container sent as tag answers this text, never the type text; the Client’s facade and the local driver’s body door mirror that precedence (round 2 of the worker-tag lane, ASTRA-1).

Data

Assignments
T
TAG_PRINTABLE_MESSAGE
NUL_MESSAGE
SURROGATE_MESSAGE
NONFINITE_MESSAGE

API

tauopt.models.Assignments

None

tauopt.models.T

‘TypeVar(…)’

class tauopt.models.Page(rows: collections.abc.Iterable[tauopt.models.T] = (), *, total: int | None = None)

Bases: list[tauopt.models.T]

One page of a list route (Client.suggestions, Client.observations): the list every caller iterates, indexes and measures, plus total – the TOTAL number of rows under the call’s filters (the service’s count; the page’s own length on the all-rows path), so a paging caller knows when it has read the last page. The attribute is total, not count, so count(value) stays the list method. copy(), copy.copy, copy.deepcopy and pickling keep total; a slice (page[1:]), a concatenation (page + rows) and a repetition (page * n) are plain lists without it, and an in-place += or extend keeps the old total. == compares the rows only: a page equals a plain list of the same rows, and two pages with different totals and the same rows are equal.

Initialization

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

total: int

None

copy() → tauopt.models.Page[tauopt.models.T]

The list method, as a Page with the same total (list.copy alone returns a plain list).

class tauopt.models.Metric(/, **data: Any)

Bases: pydantic.BaseModel

One experiment metric: objective sets the direction, strategy the role (optimized, stored-only, or an outcome constraint), and threshold the constraint/frontier bound.

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

name: str

None

objective: Literal[maximize, minimize]

‘maximize’

strategy: Literal[optimize, store, constraint]

‘optimize’

threshold: float | None

None

tauopt.models.metric_shorthand_message(name: str) → str

The 400 validation_error message both drivers answer to a bare-string metric="<name>": the shorthand names no objective, and the old expansion to {"name": name} maximized a loss silently. One text, quoted by TROUBLESHOOTING.md, built here so the Client’s pre-flight and the local driver’s door never drift.

class tauopt.models.ParameterSpec(/, **data: Any)

Bases: pydantic.BaseModel

One search-space parameter: numeric (double/integer) with exactly one of bounds or an explicit grid, or categorical with categorical_values. conditions makes it active only when each named parent categorical takes one of the listed values.

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

name: str

None

type: Literal[double, integer, categorical]

None

bounds: tuple[float, float] | None

None

log_scale: bool

False

categorical_values: tuple[str, ...] | None

None

grid: tuple[float, ...] | None

None

conditions: dict[str, tuple[str, ...]] | None

None

class tauopt.models.LinearConstraintSpec(/, **data: Any)

Bases: pydantic.BaseModel

One linear constraint over plain double parameters: the terms coefficient-weighted sum op rhs. Suggestions satisfy every linear constraint by construction.

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

terms: dict[str, float]

None

op: Literal[>=, <=]

None

rhs: float

None

class tauopt.models.ProvenanceTimings(/, **data: Any)

Bases: pydantic.BaseModel

Wall-clock split of the suggest step: GP fit vs acquisition-optimization seconds across the ask. Absent on instant rungs (random/sobol).

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

fit_s: float

None

acq_s: float

None

class tauopt.models.CenterRecord(/, **data: Any)

Bases: pydantic.BaseModel

Mirror of the engine’s center-in-bootstrap decision record (branch / action / reason).

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

branch: int

None

action: str

None

reason: str | None

None

class tauopt.models.Provenance(/, **data: Any)

Bases: pydantic.BaseModel

Mirror of the engine’s provenance receipt (identity triple).

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

engine_version: str

None

engine_sha: str

None

deps_fingerprint: str

None

strategy: str

None

config_hash: str

None

policy: str | None

None

seed: int

None

fallback_from: str | None

None

timings: tauopt.models.ProvenanceTimings | None

None

center: tauopt.models.CenterRecord | None

None

dedup: dict | None

None

selection: list[dict] | None

None

fits: list[dict] | None

None

work: list[dict] | None

None

acq_events: int | None

None

aggregation: dict | None

None

conditioning_events: list[dict] | None

None

acq_init_filters: list[dict] | None

None

fallback_attempts: list[dict] | None

None

base_noise: float | None

None

queue_wait_s: float | None

None

lane: str | None

None

attempt: int | None

None

class tauopt.models.BestObservation(/, **data: Any)

Bases: pydantic.BaseModel

One entry of best_assignments: value in single-metric mode, values for multimetric (frontier entries).

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.models.Assignments

None

value: float | None

None

values: dict[str, float] | None

None

class tauopt.models.Progress(/, **data: Any)

Bases: pydantic.BaseModel

Experiment progress snapshot: observation_count, the scalar best_observation, expected_suggest_s (the next ask’s cost estimate; populated by the hosted plane, None from the local driver), open_suggestions (the open-suggestion count, both drivers), and frontier_count (the size of the non-dominated frontier of a multimetric experiment, the hosted plane’s bounded count: None on single-metric experiments, from the local driver, and past the service’s listing bound). The scalar best is None until a non-failed observation exists, and always None for multimetric experiments (the frontier is read via best assignments instead).

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

observation_count: int

None

best_observation: tauopt.models.BestObservation | None

None

expected_suggest_s: float | None

None

open_suggestions: int | None

None

frontier_count: int | None

None

class tauopt.models.Experiment(/, **data: Any)

Bases: pydantic.BaseModel

An optimization experiment: the search space (parameters plus optional linear_constraints), the metric cluster (metric, or metrics when multimetric), and run settings (observation_budget, parallel_bandwidth, num_solutions).

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

id: str

None

name: str

None

parameters: tuple[tauopt.models.ParameterSpec, ...]

None

metric: tauopt.models.Metric

None

metrics: tuple[tauopt.models.Metric, ...] | None

None

linear_constraints: tuple[tauopt.models.LinearConstraintSpec, ...] | None

None

num_solutions: int

1

observation_budget: int | None

None

parallel_bandwidth: int

1

suggestion_ttl_s: int | None

None

metadata: dict[str, Any] | None

None

state: Literal[active, deleted]

‘active’

created: str

None

progress: tauopt.models.Progress | None

None

tauopt.models.TAG_PRINTABLE_MESSAGE

‘must be printable (no control or separator characters)’

tauopt.models.NUL_MESSAGE

‘NUL bytes are not allowed’

tauopt.models.SURROGATE_MESSAGE

‘strings must be valid UTF-8 (lone surrogates are not allowed)’

tauopt.models.NONFINITE_MESSAGE

‘non-finite numbers (NaN, Infinity) are not allowed’

tauopt.models.body_defect(value: Any) → str | None

The service’s body-defect gate, mirrored (app/api/validation.py body_defect): the first defect in a parsed body value – dict keys included, containers walked – or None: a string with a NUL, a string no UTF-8 encoder can carry (a lone surrogate), a non-finite float (bool is not float). The gate runs before any field parses, so on the hosted plane a defect inside a container sent as tag answers this text, never the type text; the Client’s facade and the local driver’s body door mirror that precedence (round 2 of the worker-tag lane, ASTRA-1).

class tauopt.models.Suggestion(/, **data: Any)

Bases: pydantic.BaseModel

One suggested trial: the assignments to evaluate next, plus the provenance receipt identifying exactly how it was derived (replay additionally needs the recorded experiment state). state flips to closed when an observation reports against it, when it is explicitly dismissed, or (hosted plane only) when the next ask finds it older than the experiment’s suggestion_ttl_s and sets expired_at.

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

id: str

None

experiment_id: str

None

assignments: tauopt.models.Assignments

None

state: Literal[_io.open, closed]

‘open’

created: str

None

expired_at: str | None

None

provenance: tauopt.models.Provenance

None

intent: dict | None

None

tag: str | None

None

class tauopt.models.Observation(/, **data: Any)

Bases: pydantic.BaseModel

One reported result for a set of assignments: value or per-metric values, optional noise via value_stddev/values_stddev, or failed=True for a failed evaluation. suggestion_id is None when the observation is reported off-suggestion (direct assignments).

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

id: str

None

experiment_id: str

None

suggestion_id: str | None

None

assignments: tauopt.models.Assignments

None

value: float | None

None

values: dict[str, float] | None

None

value_stddev: float | None

None

values_stddev: dict[str, float] | None

None

failed: bool

False

metadata: dict[str, Any] | None

None

created: str

None

class tauopt.models.BestAssignments(/, **data: Any)

Bases: pydantic.BaseModel

200-with-empty-data when nothing succeeded yet – the answer is an empty set, not a broken service. Multimetric: the Pareto frontier. num_solutions > 1: the diverse top-k.

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

count: int

0

data: tuple[tauopt.models.BestObservation, ...]

‘Field(…)’

class tauopt.models.ExperimentList(/, **data: Any)

Bases: pydantic.BaseModel

One page of GET /v1/experiments: count is the total under the call’s filters (by default the caller’s ACTIVE experiment total – the number the active-experiment cap counts – not the page size) and data the page, newest first by default, each row WITH its progress (the hosted list leaves expected_suggest_s null; read one by id for the estimate). Archived experiments are listed only with include_deleted; read one by id.

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

count: int

0

data: tuple[tauopt.models.Experiment, ...]

‘Field(…)’

class tauopt.models.Health(/, **data: Any)

Bases: pydantic.BaseModel

GET /health: status is "ok" after the service’s database round-trip (no token needed, so it says nothing about yours); the local driver answers "ok" for the in-process engine.

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

status: str

None

class tauopt.models.AuthCheck(/, **data: Any)

Bases: pydantic.BaseModel

GET /v1/auth/check: user_id is the account the token resolves to (an integer from the hosted service; the request is not counted as usage). The local driver has no accounts and answers None.

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

user_id: int | None

None