hyperstudy 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

hyperstudy/__init__.py

@@ -6,6 +6,17 @@ Usage::
 
     hs = hyperstudy.HyperStudy(api_key="hst_live_...")
     events = hs.get_events("experiment_id")
+
+Building experiments programmatically::
+
+    from hyperstudy import HyperStudy, Experiment, State, show_text
+
+    exp = Experiment(
+        name="Welcome study",
+        states=[State(id="s1", focus_component=show_text("Hello"))],
+    )
+    hs = HyperStudy(api_key="hst_live_...")
+    info = hs.create_experiment(experiment=exp)
 """
 
 from ._types import DataType, RatingKind, Scope
@@ -18,8 +29,30 @@ from .exceptions import (
     ServerError,
     ValidationError,
 )
+from .models import (
+    ComponentType,
+    DisconnectTimeout,
+    Experiment,
+    FocusComponent,
+    GlobalComponentType,
+    InstructionsPage,
+    PostExperimentQuestionnaire,
+    Role,
+    State,
+    TransitionRules,
+    WaitingRoomConfig,
+    likert_scale,
+    multiple_choice,
+    ranking,
+    show_image,
+    show_text,
+    show_video,
+    text_input,
+    vas_rating,
+    waiting,
+)
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 
 __all__ = [
     "HyperStudy",
@@ -35,4 +68,26 @@ __all__ = [
     "Scope",
     "DataType",
     "RatingKind",
+    "ComponentType",
+    "GlobalComponentType",
+    # Experiment builders
+    "Experiment",
+    "State",
+    "FocusComponent",
+    "Role",
+    "TransitionRules",
+    "WaitingRoomConfig",
+    "DisconnectTimeout",
+    "InstructionsPage",
+    "PostExperimentQuestionnaire",
+    # Component factories
+    "show_text",
+    "show_image",
+    "show_video",
+    "vas_rating",
+    "text_input",
+    "multiple_choice",
+    "waiting",
+    "likert_scale",
+    "ranking",
 ]

hyperstudy/experiments.py

@@ -2,12 +2,50 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel
+from pydantic.alias_generators import to_camel
 
 from ._display import ExperimentInfo
 from ._http import HttpTransport
 from ._pagination import fetch_all_pages
 
+if TYPE_CHECKING:
+    from .models import Experiment
+
+
+def _build_experiment_payload(
+    experiment: "Experiment | dict[str, Any] | None" = None,
+    **overrides: Any,
+) -> dict[str, Any]:
+    """Build a wire-ready dict from an Experiment instance or raw dict.
+
+    - ``Experiment`` → ``.model_dump(by_alias=True, exclude_none=True)``
+    - ``dict`` → shallow copy
+    - ``None`` → empty dict
+
+    ``overrides`` are merged on top (caller wins). Snake_case keys in
+    overrides are translated to camelCase so they actually override the
+    aliased fields of the dumped ``Experiment`` (otherwise a kwarg like
+    ``required_participants=5`` would leave the builder's
+    ``requiredParticipants`` in place and ALSO add ``required_participants``
+    to the wire payload — both keys would go).
+    """
+    if experiment is None:
+        payload: dict[str, Any] = {}
+    elif isinstance(experiment, BaseModel):
+        payload = experiment.model_dump(by_alias=True, exclude_none=True)
+    elif isinstance(experiment, dict):
+        payload = dict(experiment)
+    else:
+        raise TypeError(
+            f"experiment must be an Experiment or dict, got {type(experiment).__name__}"
+        )
+    for key, value in overrides.items():
+        payload[to_camel(key)] = value
+    return payload
+
 
 class ExperimentMixin:
     """Methods for experiment management. Mixed into the main client."""
@@ -79,33 +117,92 @@ class ExperimentMixin:
     # Write
     # ------------------------------------------------------------------
 
-    def create_experiment(self, *, name: str, **kwargs) -> ExperimentInfo:
+    def create_experiment(
+        self,
+        *,
+        experiment: "Experiment | None" = None,
+        name: str | None = None,
+        **kwargs,
+    ) -> ExperimentInfo:
         """Create a new experiment.
 
+        Two equivalent ways to call this:
+
+        - **Typed builder** (recommended): pass an :class:`Experiment` instance
+          via the ``experiment`` argument. Snake_case fields on the model are
+          converted to the camelCase wire format automatically. Fields added
+          via ``extra="allow"`` (unknown to the SDK's typed shape) and entries
+          in the per-component ``config`` dict pass through *verbatim* — use
+          camelCase keys for those.
+        - **Raw kwargs**: pass ``name=`` (required) and any additional fields
+          as keyword arguments. Backwards-compatible with hyperstudy <= 0.2.x.
+
+        When both forms are mixed, keyword arguments override fields from
+        ``experiment`` — useful for ad-hoc overrides.
+
         Args:
-            name: Experiment name (required).
-            **kwargs: Additional fields (config, states, roles, description, etc.).
+            experiment: Typed experiment definition.
+            name: Experiment name (required when ``experiment`` is omitted).
+            **kwargs: Additional fields, or overrides applied on top of
+                ``experiment``.
 
         Returns:
             The created :class:`ExperimentInfo`.
         """
-        payload = {"name": name, **kwargs}
+        if name is not None:
+            kwargs["name"] = name
+        payload = _build_experiment_payload(experiment, **kwargs)
+        if not payload.get("name"):
+            raise TypeError(
+                "create_experiment requires a 'name' "
+                "(pass name=... or experiment=Experiment(name=...))"
+            )
         body = self._transport.post("experiments", json=payload)
         data = body.get("data", [])
         record = data[0] if isinstance(data, list) and data else data
         return ExperimentInfo(record)
 
-    def update_experiment(self, experiment_id: str, **kwargs) -> dict[str, Any]:
+    def update_experiment(
+        self,
+        experiment_id: str,
+        *,
+        experiment: "Experiment | None" = None,
+        **kwargs,
+    ) -> dict[str, Any]:
         """Update an experiment.
 
         Args:
             experiment_id: ID of the experiment to update.
-            **kwargs: Fields to update (name, config, states, etc.).
+            experiment: Optional typed :class:`Experiment` carrying the new
+                fields. Snake_case → camelCase conversion is applied.
+            **kwargs: Fields to update, or overrides applied on top of
+                ``experiment``.
 
         Returns:
             Update confirmation dict.
         """
-        body = self._transport.put(f"experiments/{experiment_id}", json=kwargs)
+        payload = _build_experiment_payload(experiment, **kwargs)
+        body = self._transport.put(f"experiments/{experiment_id}", json=payload)
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data
+
+    def validate_experiment(
+        self,
+        experiment: "Experiment | dict[str, Any]",
+    ) -> dict[str, Any]:
+        """Dry-run validation of an experiment definition against the backend.
+
+        Returns the ``ValidationResultResponse`` body — typically
+        ``{"valid": True}`` on success, or ``{"valid": False, "errors": [...]}``
+        with a list of issues.
+
+        Args:
+            experiment: An :class:`Experiment` or a raw config dict.
+        """
+        if experiment is None:
+            raise TypeError("validate_experiment requires an Experiment or dict")
+        payload = _build_experiment_payload(experiment)
+        body = self._transport.post("experiments/validate", json=payload)
         data = body.get("data", [])
         return data[0] if isinstance(data, list) and data else data
 

hyperstudy/models.py

@@ -0,0 +1,327 @@
+"""Typed builders for HyperStudy experiment definitions.
+
+Mirrors the JSON schema at ``shared/schemas/experiment.schema.json`` in the
+main repo. The outer shape (Experiment / State / FocusComponent / Role) is
+typed; per-component ``config`` payloads are validated server-side and remain
+``dict[str, Any]`` here on purpose. Unknown top-level fields are preserved
+via ``extra="allow"`` so the SDK does not block on backend additions.
+"""
+
+from __future__ import annotations
+
+import uuid
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex[:8]
+
+
+class ComponentType(str, Enum):
+    """Focus component types (one per state)."""
+
+    SHOW_TEXT = "showtext"
+    SHOW_IMAGE = "showimage"
+    SHOW_VIDEO = "showvideo"
+    VAS_RATING = "vasrating"
+    TEXT_INPUT = "textinput"
+    MULTIPLE_CHOICE = "multiplechoice"
+    WAITING = "waiting"
+    CODE = "code"
+    CONTINUOUS_RATING = "continuousrating"
+    VIDEO_CHAT = "videochat"
+    TEXT_CHAT = "textchat"
+    RAPID_RATE = "rapidrate"
+    AUDIO_RECORDING = "audiorecording"
+    SPARSE_RATING = "sparserating"
+    TRIGGER = "trigger"
+    RANKING = "ranking"
+    SCANNER_PULSE_RECORDER = "scannerpulserecorder"
+    LIKERT_SCALE = "likertscale"
+    GAZE_OVERLAY = "gazeoverlay"
+
+
+class GlobalComponentType(str, Enum):
+    """Component types that may run as global (persistent) components."""
+
+    CONTINUOUS_RATING = "continuousrating"
+    VIDEO_CHAT = "videochat"
+    TEXT_CHAT = "textchat"
+    SPARSE_RATING = "sparserating"
+    SCANNER_PULSE_RECORDER = "scannerpulserecorder"
+    GAZE_OVERLAY = "gazeoverlay"
+
+
+_BASE_CONFIG = ConfigDict(
+    populate_by_name=True,
+    alias_generator=to_camel,
+    extra="allow",
+    use_enum_values=True,
+)
+
+
+class _Model(BaseModel):
+    model_config = _BASE_CONFIG
+
+
+class FocusComponent(_Model):
+    """Primary component displayed in a single state.
+
+    ``config`` is component-type-specific and validated by the backend's
+    ``componentSchemaValidator``. Use the factory helpers in this module
+    (``show_text``, ``vas_rating``, ...) for ergonomic construction.
+    """
+
+    type: ComponentType
+    config: dict[str, Any] = Field(default_factory=dict)
+    id: Optional[str] = None
+
+
+class TransitionRules(_Model):
+    """Rules governing how the experiment transitions from a state."""
+
+    type: Optional[str] = None
+    duration_ms: Optional[int] = Field(default=None, ge=0)
+
+
+class State(_Model):
+    """An experiment state — a single screen/phase."""
+
+    id: str
+    name: Optional[str] = None
+    order: Optional[int] = Field(default=None, ge=0)
+    focus_component: Optional[FocusComponent] = None
+    transition_rules: Optional[TransitionRules] = None
+    global_components_visibility: Optional[dict[str, bool]] = None
+
+
+class Role(_Model):
+    """Participant role definition for multi-participant experiments."""
+
+    name: Optional[str] = None
+    participant_count: Optional[int] = Field(default=None, ge=0)
+
+
+class WaitingRoomConfig(_Model):
+    max_wait_time_ms: Optional[int] = Field(default=None, ge=0)
+    countdown_time_ms: Optional[int] = Field(default=None, ge=0)
+
+
+class DisconnectTimeout(_Model):
+    enabled: Optional[bool] = None
+    duration_ms: Optional[int] = Field(default=None, ge=0)
+    auto_reconnect_delay: Optional[int] = Field(default=None, ge=0)
+
+
+class InstructionsPage(_Model):
+    title: Optional[str] = None
+    content: Optional[str] = None
+
+
+class PostExperimentQuestionnaire(_Model):
+    enabled: Optional[bool] = None
+    questions: Optional[list[dict[str, Any]]] = None
+
+
+class Experiment(_Model):
+    """Root experiment definition. Only ``name`` is required.
+
+    Use ``.model_dump(by_alias=True, exclude_none=True)`` to produce a
+    wire-ready payload, or pass directly to ``client.create_experiment(
+    experiment=exp)``.
+    """
+
+    name: str = Field(min_length=1)
+    description: Optional[str] = None
+    required_participants: Optional[int] = Field(default=None, ge=1)
+    randomize_states: Optional[bool] = None
+    states: Optional[list[State]] = None
+    roles: Optional[dict[str, Role]] = None
+    global_components: Optional[dict[str, dict[str, Any]]] = None
+    variables: Optional[dict[str, Any]] = None
+    waiting_room_config: Optional[WaitingRoomConfig] = None
+    disconnect_timeout: Optional[DisconnectTimeout] = None
+    completion_screen_duration_ms: Optional[int] = Field(default=None, ge=0)
+    consent_form_enabled: Optional[bool] = None
+    consent_form_title: Optional[str] = None
+    consent_form_content: Optional[str] = None
+    instructions_enabled: Optional[bool] = None
+    instructions_title: Optional[str] = None
+    instructions_content: Optional[str] = None
+    instructions_pages: Optional[list[InstructionsPage]] = None
+    post_experiment_questionnaire: Optional[PostExperimentQuestionnaire] = None
+
+
+# ---------------------------------------------------------------------------
+# Component factory helpers
+# ---------------------------------------------------------------------------
+#
+# Each factory builds a ``FocusComponent`` with the standard config keys for
+# its component type. Extra config keys pass through via ``**extra`` so users
+# can set any field the backend accepts without needing a new factory.
+
+
+# Across all factories, ``**extra`` is spread FIRST so factory-set config
+# keys win on collision. A user who accidentally passes the camelCase
+# version of a documented snake_case arg (e.g. ``outputVariable=`` instead
+# of ``output_variable=``) gets the factory's value, not their typo.
+
+
+def show_text(text: str, *, id: Optional[str] = None, **extra: Any) -> FocusComponent:
+    """Build a ``showtext`` focus component."""
+    return FocusComponent(
+        type=ComponentType.SHOW_TEXT,
+        config={**extra, "text": text},
+        id=id or _new_id(),
+    )
+
+
+def show_image(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComponent:
+    """Build a ``showimage`` focus component."""
+    return FocusComponent(
+        type=ComponentType.SHOW_IMAGE,
+        config={**extra, "url": url},
+        id=id or _new_id(),
+    )
+
+
+def show_video(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComponent:
+    """Build a ``showvideo`` focus component."""
+    return FocusComponent(
+        type=ComponentType.SHOW_VIDEO,
+        config={**extra, "url": url},
+        id=id or _new_id(),
+    )
+
+
+def vas_rating(
+    prompt: str,
+    *,
+    output_variable: str,
+    id: Optional[str] = None,
+    **extra: Any,
+) -> FocusComponent:
+    """Build a ``vasrating`` (visual analog scale) focus component."""
+    return FocusComponent(
+        type=ComponentType.VAS_RATING,
+        config={**extra, "prompt": prompt, "outputVariable": output_variable},
+        id=id or _new_id(),
+    )
+
+
+def text_input(
+    prompt: str,
+    *,
+    output_variable: str,
+    id: Optional[str] = None,
+    **extra: Any,
+) -> FocusComponent:
+    """Build a ``textinput`` focus component."""
+    return FocusComponent(
+        type=ComponentType.TEXT_INPUT,
+        config={**extra, "prompt": prompt, "outputVariable": output_variable},
+        id=id or _new_id(),
+    )
+
+
+def multiple_choice(
+    prompt: str,
+    options: list[str],
+    *,
+    output_variable: str,
+    id: Optional[str] = None,
+    **extra: Any,
+) -> FocusComponent:
+    """Build a ``multiplechoice`` focus component."""
+    return FocusComponent(
+        type=ComponentType.MULTIPLE_CHOICE,
+        config={
+            **extra,
+            "prompt": prompt,
+            "options": list(options),
+            "outputVariable": output_variable,
+        },
+        id=id or _new_id(),
+    )
+
+
+def waiting(duration_ms: int, *, id: Optional[str] = None, **extra: Any) -> FocusComponent:
+    """Build a ``waiting`` focus component."""
+    return FocusComponent(
+        type=ComponentType.WAITING,
+        config={**extra, "durationMs": int(duration_ms)},
+        id=id or _new_id(),
+    )
+
+
+def likert_scale(
+    prompt: str,
+    *,
+    output_variable: str,
+    scale_points: int = 7,
+    id: Optional[str] = None,
+    **extra: Any,
+) -> FocusComponent:
+    """Build a ``likertscale`` focus component."""
+    return FocusComponent(
+        type=ComponentType.LIKERT_SCALE,
+        config={
+            **extra,
+            "prompt": prompt,
+            "outputVariable": output_variable,
+            "scalePoints": int(scale_points),
+        },
+        id=id or _new_id(),
+    )
+
+
+def ranking(
+    prompt: str,
+    options: list[str],
+    *,
+    output_variable: str,
+    id: Optional[str] = None,
+    **extra: Any,
+) -> FocusComponent:
+    """Build a ``ranking`` focus component."""
+    return FocusComponent(
+        type=ComponentType.RANKING,
+        config={
+            **extra,
+            "prompt": prompt,
+            "options": list(options),
+            "outputVariable": output_variable,
+        },
+        id=id or _new_id(),
+    )
+
+
+__all__ = [
+    # Enums
+    "ComponentType",
+    "GlobalComponentType",
+    # Models
+    "Experiment",
+    "State",
+    "FocusComponent",
+    "TransitionRules",
+    "Role",
+    "WaitingRoomConfig",
+    "DisconnectTimeout",
+    "InstructionsPage",
+    "PostExperimentQuestionnaire",
+    # Factories
+    "show_text",
+    "show_image",
+    "show_video",
+    "vas_rating",
+    "text_input",
+    "multiple_choice",
+    "waiting",
+    "likert_scale",
+    "ranking",
+]

{hyperstudy-0.2.3.dist-info → hyperstudy-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.2.3
+Version: 0.3.0
 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
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.9
 Requires-Dist: pandas>=1.5.0
+Requires-Dist: pydantic>=2.5
 Requires-Dist: requests>=2.28.0
 Requires-Dist: tqdm>=4.60.0
 Provides-Extra: dev
@@ -125,12 +126,41 @@ experiments = hs.list_experiments()
 # Get details (with rich display in notebooks)
 exp = hs.get_experiment("exp_id")
 
-# Create / update / delete
+# Quick create / update / delete (kwargs form, backwards-compatible)
 new_exp = hs.create_experiment(name="My Study", description="...")
 hs.update_experiment("exp_id", name="Updated Name")
 hs.delete_experiment("exp_id")
 ```
 
+### Building experiments programmatically (0.3.0+)
+
+For full experiment definitions — states, components, roles — use the typed `Experiment` builder. Snake_case Python fields convert to the camelCase wire format automatically.
+
+```python
+from hyperstudy import Experiment, State, Role, show_text, vas_rating
+
+exp = Experiment(
+    name="Two-person study",
+    required_participants=2,
+    states=[
+        State(id="intro", focus_component=show_text("Welcome")),
+        State(
+            id="rate",
+            focus_component=vas_rating("Rate the clip", output_variable="rating"),
+        ),
+    ],
+    roles={"speaker": Role(name="Speaker", participant_count=1)},
+)
+
+# Dry-run validation against the backend.
+print(hs.validate_experiment(exp))  # → {"valid": True, ...}
+
+# Create.
+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.
+
 ## Deployments
 
 ```python

{hyperstudy-0.2.3.dist-info → hyperstudy-0.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-hyperstudy/__init__.py,sha256=-FMsxfDASUokTGR0-iES4eb-SUEjTuThGMqPIg-Imyw,733
+hyperstudy/__init__.py,sha256=DROd0vzdbUR2kzYSH5d8QAWVdPp6fCn1vdRGyNGNQFE,1913
 hyperstudy/_dataframe.py,sha256=8pjuMG8phMv8vwdY7sgZ-aF_6_o0UMgP2XXNp5muZ0s,3620
 hyperstudy/_display.py,sha256=5svr4NFOUJkVif57-xJzrXNOSdA5O9tKesu8UhE_jYo,1896
 hyperstudy/_downloads.py,sha256=MKUjzz9UDfo0V-n22UCdLEH2-tQxBeJMN_JoJ2spIT8,2459
@@ -7,8 +7,9 @@ hyperstudy/_pagination.py,sha256=2NbvNGW_jFQkYquSTi3SNkAmGgsbKop7J9LkGaZWwWA,181
 hyperstudy/_types.py,sha256=22JTOlM68eGJ4hg4OH-oT-hmARG2CgbhnERJ5hGxHk8,614
 hyperstudy/client.py,sha256=raAEBNxRsFPr260JWOFlOZNwmFk2SB80L2bsMoojUt0,24376
 hyperstudy/exceptions.py,sha256=z_1Ngiq-RU-1yyDI_JqvQ5CvYm2jQ_lyJ9TUbqUKKv8,1529
-hyperstudy/experiments.py,sha256=BHNf-ctKUA9uzy8Kya11nIyHPrsmOslqC_IJ5t4LxKA,4372
-hyperstudy-0.2.3.dist-info/METADATA,sha256=l1DluLkNI41NjQxrCEUAMeWMfi8jZFhXOUdC9RPb_f0,4833
-hyperstudy-0.2.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-hyperstudy-0.2.3.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
-hyperstudy-0.2.3.dist-info/RECORD,,
+hyperstudy/experiments.py,sha256=jp9kxXwumwuXz2Nq26f62BC_HnNu1lvzpFBpBFHiCeo,8180
+hyperstudy/models.py,sha256=eCXD8-5jEWVhf-eJjZ_C8-D55Uuic3awx04dYn0Q5L8,9411
+hyperstudy-0.3.0.dist-info/METADATA,sha256=P-AVQaBJ2ARQLs4zlErtNdvHCFg760BEz4gE03eye5g,6133
+hyperstudy-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hyperstudy-0.3.0.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
+hyperstudy-0.3.0.dist-info/RECORD,,