hyperstudy 0.4.2__tar.gz → 0.4.3__tar.gz

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.4.3
+
+### Features
+
+- **State randomization (V2 runner)**: `Experiment.clusters` (`Cluster`, `ClusterRule`: `type` `shuffle` | `keep`, `across_groups` `independent` | `same`). States and groups join a cluster with `cluster_id`. Each room draws its order once, so everyone in the room runs the same order. Clusters are used only while `randomize_states=True`, the same setting the legacy runner uses to shuffle each participant's order; with it `False` they are kept but not used.
+- **Variable definitions (V2 runner)**: `Experiment.variable_definitions` (`VariableDefinition` with `kind` `constant`, `random` or `computed`; `Distribution` for random variables: `uniform`, `normal`, `exponential` or `list`, drawn `per_use` or `per_room`). A TIMED state draws its duration from a random variable with `TransitionRules(type="TIMED", variable_id=...)`. Ids are generated when omitted.
+- **`Group`** model for `Experiment.groups` (`id`, `name`, `order`, `children`, `cluster_id`).
+- A constant's `value` and a list distribution's `values` are sent exactly as written on the kwargs and raw-dict paths, like other researcher-named data.
+
+### Notes
+
+- Both fields need `runtime="v2"`, the server's default for new experiments. The server refuses non-empty `variable_definitions` on any other runtime, and refuses a create or update that would make clusters or variables invalid (`ValidationError`, reasons in `details["errors"]`).
+- Pass `runtime="v2"` to `validate_experiment` when validating variable definitions: servers older than v0.7.32 do not apply create's `"v2"` default in the dry run.
+
 ## v0.4.2
 
 ### Breaking Changes

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hyperstudy
-Version: 0.4.2
+Version: 0.4.3
 Summary: Python SDK for the HyperStudy experiment platform API
 Project-URL: Homepage, https://hyperstudy.io
 Project-URL: Documentation, https://docs.hyperstudy.io/developers/python-sdk
@@ -179,6 +179,38 @@ info = hs.create_experiment(experiment=exp)
 
 Component factories cover `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. For other component types, construct directly: `FocusComponent(type=ComponentType.X, config={...})`. See the [Experiment Authoring guide](https://docs.hyperstudy.io/experimenters/api-access/experiment-authoring) for the full reference.
 
+### Randomization and variables (V2 runner)
+
+Clusters randomize the order of states and groups once per room while `randomize_states=True`; with it `False` the clusters are kept but rooms run the listed order. Variable definitions hold constants, random draws and computed values. Both need `runtime="v2"` (the server's default for new experiments). On the legacy runner, `randomize_states=True` shuffles each participant's order instead.
+
+```python
+from hyperstudy import Cluster, ClusterRule, Distribution, TransitionRules, VariableDefinition
+
+iti = VariableDefinition(
+    name="iti_ms", kind="random",
+    distribution=Distribution(type="uniform", min=500, max=1500),
+)
+exp = Experiment(
+    name="Randomized study",
+    runtime="v2",
+    randomize_states=True,
+    clusters=[Cluster(id="block", rule=ClusterRule(type="shuffle"))],
+    variable_definitions=[
+        VariableDefinition(name="endowment", kind="constant", value=10),
+        VariableDefinition(name="doubled", kind="computed", expr="endowment * 2"),
+        iti,
+    ],
+    states=[
+        State(id="a", cluster_id="block", focus_component=show_text("You have {endowment}")),
+        State(id="b", cluster_id="block", focus_component=show_text("Doubled: {doubled}")),
+        State(id="pause", focus_component=show_text("+"),
+              transition_rules=TransitionRules(type="TIMED", variable_id=iti.id)),
+    ],
+)
+```
+
+The server refuses a create or update that would make clusters or variables invalid, raising `ValidationError` with the reasons in `err.details["errors"]`.
+
 ## Deployments
 
 ```python

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/README.md

@@ -144,6 +144,38 @@ info = hs.create_experiment(experiment=exp)
 
 Component factories cover `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. For other component types, construct directly: `FocusComponent(type=ComponentType.X, config={...})`. See the [Experiment Authoring guide](https://docs.hyperstudy.io/experimenters/api-access/experiment-authoring) for the full reference.
 
+### Randomization and variables (V2 runner)
+
+Clusters randomize the order of states and groups once per room while `randomize_states=True`; with it `False` the clusters are kept but rooms run the listed order. Variable definitions hold constants, random draws and computed values. Both need `runtime="v2"` (the server's default for new experiments). On the legacy runner, `randomize_states=True` shuffles each participant's order instead.
+
+```python
+from hyperstudy import Cluster, ClusterRule, Distribution, TransitionRules, VariableDefinition
+
+iti = VariableDefinition(
+    name="iti_ms", kind="random",
+    distribution=Distribution(type="uniform", min=500, max=1500),
+)
+exp = Experiment(
+    name="Randomized study",
+    runtime="v2",
+    randomize_states=True,
+    clusters=[Cluster(id="block", rule=ClusterRule(type="shuffle"))],
+    variable_definitions=[
+        VariableDefinition(name="endowment", kind="constant", value=10),
+        VariableDefinition(name="doubled", kind="computed", expr="endowment * 2"),
+        iti,
+    ],
+    states=[
+        State(id="a", cluster_id="block", focus_component=show_text("You have {endowment}")),
+        State(id="b", cluster_id="block", focus_component=show_text("Doubled: {doubled}")),
+        State(id="pause", focus_component=show_text("+"),
+              transition_rules=TransitionRules(type="TIMED", variable_id=iti.id)),
+    ],
+)
+```
+
+The server refuses a create or update that would make clusters or variables invalid, raising `ValidationError` with the reasons in `err.details["errors"]`.
+
 ## Deployments
 
 ```python

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.4.2"
+version = "0.4.3"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/src/hyperstudy/__init__.py

@@ -31,13 +31,17 @@ from .exceptions import (
 )
 from .models import (
     AgentConfig,
+    Cluster,
+    ClusterRule,
     ComponentType,
     DisconnectTimeout,
+    Distribution,
     EngineTurnDetection,
     Experiment,
     ExperimenterMessageStyle,
     FocusComponent,
     GlobalComponentType,
+    Group,
     Guardrails,
     InstructionsPage,
     Persona,
@@ -49,6 +53,7 @@ from .models import (
     Role,
     State,
     TransitionRules,
+    VariableDefinition,
     VoiceTranscription,
     VoiceTurnTaking,
     WaitingRoomConfig,
@@ -63,7 +68,7 @@ from .models import (
     waiting,
 )
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 
 __all__ = [
     "HyperStudy",
@@ -98,6 +103,11 @@ __all__ = [
     "VoiceTranscription",
     "ExperimenterMessageStyle",
     "TransitionRules",
+    "Group",
+    "Cluster",
+    "ClusterRule",
+    "VariableDefinition",
+    "Distribution",
     "WaitingRoomConfig",
     "DisconnectTimeout",
     "InstructionsPage",

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/src/hyperstudy/experiments.py

@@ -211,6 +211,11 @@ class ExperimentMixin:
         ``{"valid": True}`` on success, or ``{"valid": False, "errors": [...]}``
         with a list of issues.
 
+        Set ``runtime`` explicitly when the definition has
+        ``variable_definitions``: servers older than v0.7.32 do not default
+        it to ``"v2"`` here the way :meth:`create_experiment` does, and
+        report variable definitions on any other runtime as an error.
+
         Args:
             experiment: An :class:`Experiment` or a raw config dict.
         """

{hyperstudy-0.4.2 → hyperstudy-0.4.3}/src/hyperstudy/models.py

@@ -37,10 +37,13 @@ _FREEFORM_MAP_FIELDS = frozenset({
 # (engineTurnDetection), and names the researcher chose (cognition contexts,
 # stimulus mappings, free-form metadata). Matching on position, not the bare
 # key, keeps a variable or role that happens to be named "metadata" a variable.
+# A variable definition's constant ``value`` and a list distribution's
+# ``values`` are researcher data, so their keys are kept too.
 _VERBATIM_FIELDS = frozenset({
     (None, "extraParams"), (None, "cognition"), (None, "stimulusMappings"),
     (None, "metadata"), (None, "prolific_config"),
     ("voiceTurnTaking", "engineTurnDetection"),
+    ("variableDefinitions", "value"), ("distribution", "values"),
 })
 
 # Experiment fields the backend stores under snake_case names.
@@ -151,14 +154,23 @@ class FocusComponent(_Model):
 
 
 class TransitionRules(_Model):
-    """Rules governing how the experiment transitions from a state."""
+    """Rules governing how the experiment transitions from a state.
+
+    On the V2 runner a ``"TIMED"`` state can draw its duration from a random
+    variable instead of a fixed value: set ``variable_id`` to the id of a
+    :class:`VariableDefinition` with ``kind="random"``.
+    """
 
     type: Optional[str] = None
     duration_ms: Optional[int] = Field(default=None, ge=0)
+    variable_id: Optional[str] = None
 
 
 class State(_Model):
-    """An experiment state — a single screen/phase."""
+    """An experiment state — a single screen/phase.
+
+    ``cluster_id`` (V2 runner) makes the state a member of a :class:`Cluster`.
+    """
 
     id: str = Field(min_length=1)
     name: Optional[str] = None
@@ -166,6 +178,108 @@ class State(_Model):
     focus_component: Optional[FocusComponent] = None
     transition_rules: Optional[TransitionRules] = None
     global_components_visibility: Optional[dict[str, bool]] = None
+    cluster_id: Optional[str] = None
+
+
+class Group(_Model):
+    """A group of states that run together.
+
+    ``children`` are state ids, in run order. ``order`` places the group
+    among the top-level states (lone states and groups share one sequence).
+    ``cluster_id`` (V2 runner) makes the whole group a member of a
+    :class:`Cluster`, moving as one unit; its states can carry their own
+    ``cluster_id`` to be randomized within the group.
+    """
+
+    id: str = Field(min_length=1)
+    name: Optional[str] = None
+    order: Optional[int] = Field(default=None, ge=0)
+    children: Optional[list[str]] = None
+    cluster_id: Optional[str] = None
+
+
+class ClusterRule(_Model):
+    """How a cluster orders its members.
+
+    ``type``: ``"shuffle"`` (a uniformly random order) or ``"keep"`` (the
+    authored order). ``across_groups``, for a cluster used inside groups:
+    ``"independent"`` (default; each group draws its own order) or
+    ``"same"`` (one order applied to every group using the cluster, which
+    must then all have the same number of members).
+    """
+
+    type: str  # "shuffle" | "keep"
+    across_groups: Optional[str] = None  # "independent" (default) | "same"
+
+
+class Cluster(_Model):
+    """A randomization cluster (V2 runner only; ignored on the legacy runner).
+
+    Used only while the experiment's ``randomize_states`` is True; with it
+    False the clusters are kept but rooms run the listed order.
+
+    States and groups join a cluster by setting ``cluster_id`` to its ``id``.
+    A cluster applies among siblings: the top-level items (lone states and
+    whole groups), or the states inside one group. Members trade places
+    among the positions they occupy; everything else stays where it is. Each
+    room draws its order once, so everyone in the room runs the same order.
+    """
+
+    id: str = Field(default_factory=_new_id, min_length=1)
+    name: Optional[str] = None
+    color: Optional[str] = None
+    rule: ClusterRule
+
+
+class Distribution(_Model):
+    """The distribution a random variable draws from.
+
+    - ``type="uniform"``: ``min``, ``max``
+    - ``type="normal"``: ``mean``, ``sd``; optional ``min`` / ``max`` truncate it
+    - ``type="exponential"``: ``mean``; ``min`` (default 0) plus an exponential
+      with this mean, optionally cut at ``max``
+    - ``type="list"``: ``values`` and ``sampling`` (``"with_replacement"``,
+      ``"without_replacement"`` — a deck reshuffled when exhausted — or
+      ``"sequential"``, in order, wrapping)
+    """
+
+    type: str  # "uniform" | "normal" | "exponential" | "list"
+    min: Optional[float] = None
+    max: Optional[float] = None
+    mean: Optional[float] = None
+    sd: Optional[float] = Field(default=None, gt=0)
+    values: Optional[list[Any]] = Field(default=None, min_length=1, max_length=1000)
+    sampling: Optional[str] = None  # list: with_replacement | without_replacement | sequential
+
+
+class VariableDefinition(_Model):
+    """A variable the experiment defines (V2 runner only).
+
+    ``kind`` decides which fields apply:
+
+    - ``"constant"``: ``value`` (text, a number, true/false, a list or a dict)
+    - ``"random"``: ``distribution``, ``draw`` (``"per_use"``, the default: a
+      fresh value for each state that takes its duration from it;
+      ``"per_room"``: one value for the room) and ``round`` (decimals kept,
+      default 0). Values are drawn when the room is planned, so everyone in
+      the room gets the same ones.
+    - ``"computed"``: ``expr``, an expression over other variables
+
+    ``name`` is what component text (``{name}``) and expressions read; ``id``
+    is what a TIMED state's ``TransitionRules.variable_id`` references, and is
+    generated when omitted. The server refuses non-empty definitions unless
+    the experiment's ``runtime`` is ``"v2"``, and refuses a save that makes
+    them invalid (``ValidationError``, messages in ``details["errors"]``).
+    """
+
+    id: str = Field(default_factory=_new_id, min_length=1)
+    name: str = Field(pattern=r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+    kind: str  # "constant" | "random" | "computed"
+    value: Optional[Any] = None
+    distribution: Optional[Distribution] = None
+    draw: Optional[str] = None  # random: "per_use" (default) | "per_room"
+    round: Optional[int] = Field(default=None, ge=0, le=6)
+    expr: Optional[str] = Field(default=None, min_length=1, max_length=2000)
 
 
 class Role(_Model):
@@ -371,10 +485,15 @@ class Experiment(_Model):
     name: str = Field(min_length=1)
     description: Optional[str] = None
     required_participants: Optional[int] = Field(default=None, ge=1)
-    runtime: Optional[str] = None  # "v2" required for agent-only deployments
+    # "v2" (the server's default for new experiments) or "v1" (legacy).
+    # Agents, clusters and variable_definitions need "v2".
+    runtime: Optional[str] = None
     agent_config: Optional[AgentConfig] = None
-    randomize_states: Optional[bool] = None
+    randomize_states: Optional[bool] = None  # legacy: shuffle per participant; v2: use clusters
     states: Optional[list[State]] = None
+    groups: Optional[list[Group]] = None
+    clusters: Optional[list[Cluster]] = Field(default=None, max_length=100)
+    variable_definitions: Optional[list[VariableDefinition]] = Field(default=None, max_length=500)
     roles: Optional[dict[str, Role]] = None
     global_components: Optional[dict[GlobalComponentType, dict[str, Any]]] = None
     variables: Optional[dict[str, Any]] = None
@@ -561,12 +680,18 @@ __all__ = [
     "State",
     "FocusComponent",
     "TransitionRules",
+    "Group",
     "Role",
     "WaitingRoomConfig",
     "DisconnectTimeout",
     "InstructionsPage",
     "PostExperimentQuestionnaire",
     "ExperimenterMessageStyle",
+    # Randomization and variables (V2 runner)
+    "Cluster",
+    "ClusterRule",
+    "VariableDefinition",
+    "Distribution",
     # Agent models
     "AgentConfig",
     "PromptLayer",

hyperstudy-0.4.3/tests/test_randomization_variables.py

@@ -0,0 +1,291 @@
+"""V2 randomization clusters and variable definitions on experiments.
+
+The v3 API accepts ``clusters`` and ``variableDefinitions`` on create and
+update, states and groups join a cluster with ``clusterId``, and a TIMED state
+draws its duration from a random variable with ``transitionRules.variableId``.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+import responses
+from pydantic import ValidationError as PydanticValidationError
+
+from hyperstudy import (
+    Cluster,
+    ClusterRule,
+    Distribution,
+    Experiment,
+    Group,
+    HyperStudy,
+    State,
+    TransitionRules,
+    VariableDefinition,
+    show_text,
+)
+from hyperstudy.exceptions import ValidationError
+
+from .conftest import BASE_URL, envelope
+
+
+def _sent(call_index: int = 0) -> dict:
+    return json.loads(responses.calls[call_index].request.body)
+
+
+def _randomized_experiment() -> Experiment:
+    return Experiment(
+        name="Randomized study",
+        runtime="v2",
+        randomize_states=True,
+        clusters=[
+            Cluster(id="block", name="Block", rule=ClusterRule(type="shuffle")),
+            Cluster(id="inner", rule=ClusterRule(type="shuffle", across_groups="same")),
+        ],
+        variable_definitions=[
+            VariableDefinition(
+                id="v_end", name="endowment", kind="constant", value={"first_offer": 3}
+            ),
+            VariableDefinition(
+                id="v_iti",
+                name="iti_ms",
+                kind="random",
+                distribution=Distribution(type="uniform", min=500, max=1500),
+                draw="per_use",
+                round=0,
+            ),
+            VariableDefinition(
+                id="v_pick",
+                name="pick",
+                kind="random",
+                distribution=Distribution(
+                    type="list",
+                    values=[{"face_id": 1}, {"face_id": 2}],
+                    sampling="without_replacement",
+                ),
+                draw="per_room",
+            ),
+            VariableDefinition(id="v_dbl", name="doubled", kind="computed", expr="endowment * 2"),
+        ],
+        states=[
+            State(id="a", cluster_id="block", focus_component=show_text("A", id="fa")),
+            State(id="b", cluster_id="block", focus_component=show_text("B", id="fb")),
+            State(
+                id="pause",
+                focus_component=show_text("+", id="fp"),
+                transition_rules=TransitionRules(type="TIMED", variable_id="v_iti"),
+            ),
+            State(id="g1", cluster_id="inner"),
+            State(id="g2", cluster_id="inner"),
+        ],
+        groups=[Group(id="grp", name="Group", order=3, children=["g1", "g2"], cluster_id="block")],
+    )
+
+
+@responses.activate
+def test_create_sends_clusters_and_variable_definitions_in_wire_format(api_key):
+    responses.post(f"{BASE_URL}/experiments", json=envelope({"id": "exp-1"}), status=201)
+
+    HyperStudy(api_key=api_key).create_experiment(experiment=_randomized_experiment())
+    sent = _sent()
+
+    assert sent["runtime"] == "v2"
+    assert sent["randomizeStates"] is True
+    assert sent["clusters"] == [
+        {"id": "block", "name": "Block", "rule": {"type": "shuffle"}},
+        {"id": "inner", "rule": {"type": "shuffle", "acrossGroups": "same"}},
+    ]
+    by_id = {v["id"]: v for v in sent["variableDefinitions"]}
+    # A constant's value is researcher data: its keys are not camelCased.
+    assert by_id["v_end"] == {
+        "id": "v_end",
+        "name": "endowment",
+        "kind": "constant",
+        "value": {"first_offer": 3},
+    }
+    assert by_id["v_iti"] == {
+        "id": "v_iti",
+        "name": "iti_ms",
+        "kind": "random",
+        "distribution": {"type": "uniform", "min": 500, "max": 1500},
+        "draw": "per_use",
+        "round": 0,
+    }
+    assert by_id["v_pick"]["distribution"]["values"] == [{"face_id": 1}, {"face_id": 2}]
+    assert by_id["v_dbl"] == {
+        "id": "v_dbl",
+        "name": "doubled",
+        "kind": "computed",
+        "expr": "endowment * 2",
+    }
+    assert "variable_definitions" not in sent
+
+    states = {s["id"]: s for s in sent["states"]}
+    assert states["a"]["clusterId"] == "block"
+    assert states["pause"]["transitionRules"] == {"type": "TIMED", "variableId": "v_iti"}
+    assert sent["groups"] == [
+        {"id": "grp", "name": "Group", "order": 3, "children": ["g1", "g2"], "clusterId": "block"}
+    ]
+
+
+@responses.activate
+def test_update_kwargs_with_plain_dicts_convert_schema_keys_only(api_key):
+    """Kwargs camelCase schema keys but keep a constant's value and list values as written."""
+    responses.put(
+        f"{BASE_URL}/experiments/exp-1", json=envelope({"id": "exp-1", "updated": True}), status=200
+    )
+
+    result = HyperStudy(api_key=api_key).update_experiment(
+        "exp-1",
+        clusters=[{"id": "block", "rule": {"type": "keep", "across_groups": "independent"}}],
+        variable_definitions=[
+            {
+                "id": "v1",
+                "name": "prices",
+                "kind": "constant",
+                "value": {"base_price": 2, "max_price": 9},
+            },
+            {
+                "id": "v2",
+                "name": "cue",
+                "kind": "random",
+                "draw": "per_room",
+                "distribution": {
+                    "type": "list",
+                    "values": [{"cue_side": "left"}],
+                    "sampling": "sequential",
+                },
+            },
+        ],
+    )
+
+    assert result == {"id": "exp-1", "updated": True}
+    assert _sent() == {
+        "clusters": [{"id": "block", "rule": {"type": "keep", "acrossGroups": "independent"}}],
+        "variableDefinitions": [
+            {
+                "id": "v1",
+                "name": "prices",
+                "kind": "constant",
+                "value": {"base_price": 2, "max_price": 9},
+            },
+            {
+                "id": "v2",
+                "name": "cue",
+                "kind": "random",
+                "draw": "per_room",
+                "distribution": {
+                    "type": "list",
+                    "values": [{"cue_side": "left"}],
+                    "sampling": "sequential",
+                },
+            },
+        ],
+    }
+
+
+@responses.activate
+def test_update_kwargs_accept_typed_models(api_key):
+    responses.put(
+        f"{BASE_URL}/experiments/exp-1", json=envelope({"id": "exp-1", "updated": True}), status=200
+    )
+
+    HyperStudy(api_key=api_key).update_experiment(
+        "exp-1",
+        clusters=[Cluster(id="c1", rule=ClusterRule(type="shuffle", across_groups="same"))],
+        variable_definitions=[VariableDefinition(id="v1", name="n", kind="constant", value=[1, 2])],
+    )
+
+    assert _sent() == {
+        "clusters": [{"id": "c1", "rule": {"type": "shuffle", "acrossGroups": "same"}}],
+        "variableDefinitions": [{"id": "v1", "name": "n", "kind": "constant", "value": [1, 2]}],
+    }
+
+
+@responses.activate
+def test_get_config_round_trips_through_the_typed_builder(api_key):
+    """A definition read back from /config rebuilds into typed models and re-sends unchanged."""
+    stored = Experiment.model_validate(
+        _randomized_experiment().model_dump(by_alias=True, exclude_none=True)
+    )
+    record = {"id": "exp-1", **stored.model_dump(by_alias=True, exclude_none=True)}
+    responses.get(f"{BASE_URL}/experiments/exp-1/config", json=envelope(record), status=200)
+
+    config = HyperStudy(api_key=api_key).get_experiment_config("exp-1")
+
+    assert config["clusters"][1]["rule"]["acrossGroups"] == "same"
+    rebuilt = Experiment.model_validate(config)
+    assert isinstance(rebuilt.clusters[0], Cluster)
+    assert isinstance(rebuilt.variable_definitions[1], VariableDefinition)
+    assert isinstance(rebuilt.variable_definitions[1].distribution, Distribution)
+    assert rebuilt.states[2].transition_rules.variable_id == "v_iti"
+    assert rebuilt.groups[0].cluster_id == "block"
+    assert rebuilt.variable_definitions[0].value == {"first_offer": 3}
+    dumped = rebuilt.model_dump(by_alias=True, exclude_none=True)
+    dumped.pop("id")
+    assert dumped == stored.model_dump(by_alias=True, exclude_none=True)
+
+
+@responses.activate
+def test_refused_randomization_raises_validation_error_with_reasons(api_key):
+    responses.put(
+        f"{BASE_URL}/experiments/exp-1",
+        json={
+            "status": "error",
+            "error": {
+                "code": "VALIDATION_ERROR",
+                "message": "Invalid randomization",
+                "details": {"errors": ['cluster "c1" has unknown rule "sort"']},
+            },
+        },
+        status=400,
+    )
+
+    with pytest.raises(ValidationError) as caught:
+        HyperStudy(api_key=api_key).update_experiment(
+            "exp-1", clusters=[{"id": "c1", "rule": {"type": "sort"}}]
+        )
+
+    assert caught.value.code == "VALIDATION_ERROR"
+    assert caught.value.details["errors"] == ['cluster "c1" has unknown rule "sort"']
+
+
+def test_generated_ids_let_a_timed_state_reference_its_variable():
+    iti = VariableDefinition(
+        name="iti_ms",
+        kind="random",
+        distribution=Distribution(type="exponential", mean=800, max=3000),
+    )
+    cluster = Cluster(rule=ClusterRule(type="shuffle"))
+    assert iti.id and cluster.id and iti.id != cluster.id
+    state = State(id="s", transition_rules=TransitionRules(type="TIMED", variable_id=iti.id))
+    assert (
+        state.model_dump(by_alias=True, exclude_none=True)["transitionRules"]["variableId"]
+        == iti.id
+    )
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {"name": "1st", "kind": "constant", "value": 1},  # name starts with a digit
+        {"name": "x", "kind": "random", "round": 7},  # more decimals than the server keeps
+        {"name": "x", "kind": "computed", "expr": ""},  # empty expression
+    ],
+)
+def test_variable_definition_rejects_what_the_server_would(kwargs):
+    with pytest.raises(PydanticValidationError):
+        VariableDefinition(**kwargs)
+
+
+def test_distribution_rejects_non_positive_sd_and_empty_list():
+    with pytest.raises(PydanticValidationError):
+        Distribution(type="normal", mean=0, sd=0)
+    with pytest.raises(PydanticValidationError):
+        Distribution(type="list", values=[], sampling="sequential")
+
+
+def test_too_many_clusters_fail_when_the_model_is_built():
+    with pytest.raises(PydanticValidationError):
+        Experiment(name="x", clusters=[Cluster(rule=ClusterRule(type="keep")) for _ in range(101)])