hyperstudy 0.4.2__py3-none-any.whl → 0.4.3__py3-none-any.whl

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/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/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.2.dist-info → hyperstudy-0.4.3.dist-info}/METADATA

@@ -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.dist-info → hyperstudy-0.4.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hyperstudy/__init__.py,sha256=8yoNbRsLUNtzRWR98EHvrb78hcr4YeN7DoTy7rnnsA0,2369
+hyperstudy/__init__.py,sha256=RVX7QgHV4AXn0V40p-i2zsXv1bT5kYA7AgVnlRuTgDs,2545
 hyperstudy/_dataframe.py,sha256=8pjuMG8phMv8vwdY7sgZ-aF_6_o0UMgP2XXNp5muZ0s,3620
 hyperstudy/_display.py,sha256=5svr4NFOUJkVif57-xJzrXNOSdA5O9tKesu8UhE_jYo,1896
 hyperstudy/_downloads.py,sha256=8s-Ml0oK_3f5CNn9hSp0z5d1oyDBR7ldPYVPbDo0zss,2616
@@ -7,10 +7,10 @@ hyperstudy/_pagination.py,sha256=2NbvNGW_jFQkYquSTi3SNkAmGgsbKop7J9LkGaZWwWA,181
 hyperstudy/_types.py,sha256=nREuLxEe4ylnyxRPyR1kgBh0V4fDKf5OmfiLEmTkg-o,734
 hyperstudy/client.py,sha256=DRKDmLND65bxXAIBO9EDK2IikX6RJ_6O0GgmyI6ISTI,40319
 hyperstudy/exceptions.py,sha256=z_1Ngiq-RU-1yyDI_JqvQ5CvYm2jQ_lyJ9TUbqUKKv8,1529
-hyperstudy/experiments.py,sha256=cQN0O6sPeSAJ9qqIGdIIR5Mvu1Mf7HJ9BKUc01_-cn0,8695
-hyperstudy/models.py,sha256=Tdi5ygqDwkA-p9ibqdT-70zCaMi9BBIZSVPL4Y6e6Yg,20288
+hyperstudy/experiments.py,sha256=TkWHncrQmUlEKAmVHHCeXwekSFDqQ6lxu81gW6J-cOE,8973
+hyperstudy/models.py,sha256=X3y5kpBH1YZLp9VYoZ8ChobIYC_oIKH5PoP73GyBrCk,25691
 hyperstudy/personas.py,sha256=T4cbI0wWfokAthxKzgM73NA_we3mBtR-j_lcn3iYl4Q,5328
-hyperstudy-0.4.2.dist-info/METADATA,sha256=aYnlSHF7l0VJ7ruRo-P0mafpdEHVtmyZOlXwJO_6dQc,10499
-hyperstudy-0.4.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
-hyperstudy-0.4.2.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
-hyperstudy-0.4.2.dist-info/RECORD,,
+hyperstudy-0.4.3.dist-info/METADATA,sha256=JCtqw_t8ZDw13s_HEIDvpuKyjH2lpblfS2iqcQnFGjs,12049
+hyperstudy-0.4.3.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hyperstudy-0.4.3.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
+hyperstudy-0.4.3.dist-info/RECORD,,