Use duplicate intents#

With dedup on (the default), the engine never re-suggests an observed or still-open point. An intent is a typed request for exactly such a duplicate: intents=[{"kind": ..., "source_id": ..., "ordinal": ...}] on suggest. The engine recomputes whether the request is authorized and refuses with a typed reason otherwise. The dedup rules themselves are in Dedup and completion. Both runs on this page use the local driver; the assignments printed depend on the machine and dependency set.

A duplicate is granted only when the engine has no unique point left to offer: after a finite space is proven exhausted (SpaceExhausted) or after the duplicate-repair search runs dry (409 unique_candidate_unavailable). When the unique search fills every requested slot, every enabled intent is refused with no_unfilled_slots; a grant needs an unfilled slot (a proven exhaustion or a repair-search shortfall).

Before you start#

  • Enable the kind in the config’s duplicate_intents block; a kind without a block is refused as disabled.

  • Keep dedup on. An explicit config={"dedup": False} with intents= is refused: intents require dedup=true on the config.

  • Use a single objective; on multimetric experiments every intent is refused as multimetric_inert.

  • source_id is the canonical assignment key: the assignment dict as JSON with sorted keys, compact separators, and values typed per parameter (int for integers, float for doubles, str for categoricals). A grant echoes it in suggestion.intent.

Request a variance replication#

A variance replication re-evaluates an already-observed point to measure noise. The policy keeps a queue of observed points ordered by fewest replicas so far, then best value, then key, and grants only its head; ordinal must equal the number of replicas that point already has (0 for the first), and max_replicas (default 3) caps them.

import json

from tauopt import ApiError, Client, SpaceExhausted

# the config that ENABLES the kind; without the block every request is refused as "disabled"
CONFIG = {"strategy": "auto", "duplicate_intents": {"variance_replication": {"max_replicas": 3}}}

client = Client(driver="local")
exp = client.create_experiment(
    name="replicate-the-best",
    parameters=[
        {"name": "level", "type": "integer", "bounds": (1, 2)},
        {"name": "kind", "type": "categorical", "categorical_values": ["a", "b"]},
    ],
    metric={"name": "score", "objective": "maximize"},
)


def score(a):
    return {"a": 1.0, "b": 2.0}[a["kind"]] * a["level"]


observed = {}
while True:   # drain the four-point space until exhaustion is proven
    try:
        sug = client.suggest(exp.id, config=CONFIG)
    except SpaceExhausted as e:
        print("exhausted:", e.error_type, "proof:", e.details["dedup"]["exhaust_proof"])
        break
    obs = client.observe(exp.id, suggestion_id=sug.id, value=score(sug.assignments))
    observed[obs.id] = obs

best = client.best(exp.id).data[0]
# the canonical assignment key: sorted keys, compact separators, values typed per parameter
source_id = json.dumps(best.assignments, sort_keys=True, separators=(",", ":"))
print("source_id:", source_id)

# ordinal 0 = the first replica of that point
sug = client.suggest(
    exp.id, config=CONFIG,
    intents=[{"kind": "variance_replication", "source_id": source_id, "ordinal": 0}],
)
print("granted:", sug.intent, sug.assignments)
print("origin:", sug.provenance.dedup["per_draft_origin"], "refusals:", sug.provenance.dedup["intent_refusals"])
client.observe(exp.id, suggestion_id=sug.id, value=score(sug.assignments) + 0.1)

# a second request for the same point is refused: another point now heads the queue
try:
    client.suggest(
        exp.id, config=CONFIG,
        intents=[{"kind": "variance_replication", "source_id": source_id, "ordinal": 0}],
    )
except SpaceExhausted as e:
    print("refused:", e.details["dedup"]["intent_refusals"])

# intents require the dedup default
try:
    client.suggest(
        exp.id, config={"strategy": "auto", "dedup": False},
        intents=[{"kind": "variance_replication", "source_id": source_id, "ordinal": 1}],
    )
except ApiError as e:
    print(e)

exhausted: space_exhausted proof: True
source_id: {"kind":"b","level":2}
granted: {'kind': 'variance_replication', 'source_id': '{"kind":"b","level":2}', 'ordinal': 0} {'level': 2, 'kind': 'b'}
origin: ['intent_grant'] refusals: []
refused: [{'kind': 'variance_replication', 'source_id': '{"kind":"b","level":2}', 'ordinal': 0, 'reason': 'source_not_policy_selected'}]
[400] validation_error: intents require dedup=true on the config

After the first replica, the replicated point has one replica and the other three have none, so the queue head moves and the repeat request is refused as source_not_policy_selected.

Request a liar verification#

A liar verification re-asks a still-open point whose pessimistic placeholder value (the constant liar the GP rungs use for pending points) may be masking a worker that will never report. The engine grants one only for a pending point that opened under a config carrying a duplicate_intents block (either kind) or a queue_selection block, which is what stamps its placeholder lie, has had at least 3 observations land after it, and whose placeholder sits within 10 percent of the incumbent (the band is 0.1 * max(abs(incumbent), 1), so an absolute 0.1 when the incumbent’s magnitude is below 1); the requesting config must enable liar_verification; max_verifications (default 1) caps grants per point, and one is granted per ask. The run keeps every value equal so the placeholder qualifies.

import json

from tauopt import Client, SpaceExhausted

CONFIG = {"strategy": "auto", "duplicate_intents": {"liar_verification": {"max_verifications": 1}}}

client = Client(driver="local")
exp = client.create_experiment(
    name="verify-a-stale-pending-point",
    parameters=[
        {"name": "level", "type": "integer", "bounds": (1, 3)},
        {"name": "kind", "type": "categorical", "categorical_values": ["a", "b"]},
    ],
    metric={"name": "score", "objective": "maximize"},
    parallel_bandwidth=2,   # one slot stays held by the pending point
)

first = client.suggest(exp.id, config=CONFIG)
client.observe(exp.id, suggestion_id=first.id, value=1.0)

pending = client.suggest(exp.id, config=CONFIG)   # handed out, never reported back
print("pending:", pending.id, pending.assignments)

while True:   # the other four points land, all at the same value
    try:
        sug = client.suggest(exp.id, config=CONFIG)
    except SpaceExhausted:
        break
    client.observe(exp.id, suggestion_id=sug.id, value=1.0)

source_id = json.dumps(pending.assignments, sort_keys=True, separators=(",", ":"))
sug = client.suggest(
    exp.id, config=CONFIG,
    intents=[{"kind": "liar_verification", "source_id": source_id, "ordinal": 0}],
)
print("granted:", sug.intent)
print("same assignments as the pending point:", sug.assignments == pending.assignments)

pending: local-1-s2 {'level': 3, 'kind': 'a'}
granted: {'kind': 'liar_verification', 'source_id': '{"kind":"a","level":3}', 'ordinal': 0}
same assignments as the pending point: True

Read refusals#

A refusal never raises on its own. On an ask that returned a suggestion, read suggestion.provenance.dedup["intent_refusals"]; on a draftless ask (SpaceExhausted, or a 409 unique_candidate_unavailable), read e.details["dedup"]["intent_refusals"]. Each entry carries kind, source_id, ordinal, and one reason, checked in this order:

  • disabled: the config has no block for that kind.

  • multimetric_inert: the experiment optimizes two or more metrics.

  • no_unfilled_slots: the unique search filled every slot.

  • per_ask_limit: a liar verification was already granted on this ask.

  • empty_q: no source qualifies (nothing observed, for a replica; no stale pending point near the incumbent, for a verification).

  • source_not_in_q: the source_id is not a qualifying source; an observation id in place of the canonical assignment key lands here.

  • source_not_policy_selected: the source qualifies, but another one heads the queue.

  • ordinal_not_next: the ordinal is not the next expected count.

A grant shows up as intent_grant in provenance.dedup["per_draft_origin"]. The duplicate_intents config blocks and their caps are in Strategies and config.