hyperstudy 0.2.3__tar.gz → 0.3.1__tar.gz

hyperstudy-0.3.1/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## v0.3.1
+
+### Features
+
+- `download_recording` / `download_recordings` now mint a signed download URL via the recordings download endpoint (using each recording's `downloadPath`) and fall back to the legacy `downloadUrl`/`url` for older GCS-only recordings. Fixes downloads failing after the backend list endpoint stopped embedding signed URLs.
+
+### Fixes
+
+- Snake_case→camelCase conversion is now recursive for the raw-dict and `**kwargs` paths: nested keys (e.g. `waiting_room_config={"max_wait_time_ms": 5000}` → `{"waitingRoomConfig": {"maxWaitTimeMs": 5000}}`) and factory `**extra` kwargs are converted. Free-form map fields (`variables`, `roles`, `globalComponents`, `globalComponentsVisibility`) preserve their user-defined keys while still converting nested schema fields. Previously nested/extra snake_case keys were silently dropped on the wire.
+- Downloads are now atomic: each file streams to `<dest>.part` and is renamed on success, so a mid-stream failure never destroys a pre-existing complete file. `skip_existing` again skips when `fileSize` is unknown (an existing file is necessarily complete).
+- `update_experiment()` with no fields now raises `ValueError` instead of issuing an empty PUT.
+- `State.id` enforces `min_length=1`; `Experiment.global_components` keys are validated against `GlobalComponentType` (rejected at construction, still serialized as strings on the wire).
+- `FocusComponent.id` is auto-generated when omitted, including direct construction without a factory helper.
+
+
+## v0.3.0
+
+### Features
+
+- Typed experiment builders for programmatic authoring. New top-level exports: `Experiment`, `State`, `FocusComponent`, `Role`, `WaitingRoomConfig`, `DisconnectTimeout`, `InstructionsPage`, `PostExperimentQuestionnaire`, `TransitionRules`, `ComponentType`, `GlobalComponentType`. Snake_case Python fields are converted to the camelCase wire format automatically; unknown top-level fields are preserved via `extra="allow"` so the SDK doesn't block on backend schema additions.
+- Component factory helpers: `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. Extra kwargs pass through to the component `config` for any backend-supported field.
+- `create_experiment` and `update_experiment` now accept an `experiment=Experiment(...)` argument alongside the existing `**kwargs` form. When both are given, kwargs override builder fields.
+- New `validate_experiment(experiment)` method — dry-run against `POST /experiments/validate`.
+- Schema-drift guard test: vendored copy of `experiment.schema.json` is checked against `ComponentType` / `GlobalComponentType` / required-field declarations so backend additions surface in CI.
+
+### Backwards Compatibility
+
+- `create_experiment(name=..., **kwargs)` continues to work unchanged.
+- `update_experiment(experiment_id, **kwargs)` continues to work unchanged.
+
+### Dependencies
+
+- Adds `pydantic>=2.5`.
+
+## v0.2.0
+
+### Features
+
+- Convenience methods for common event categories: `get_questionnaire`, `get_instructions`, `get_consent`
+- Deployment management: `list_deployments`, `get_deployment`, `get_deployment_sessions`
+- API warning surfacing: backend `_warnings` metadata now emitted via Python's `warnings` module
+- `get_all_data` now includes `ratings_sparse`, `questionnaire`, `instructions`, and `consent`
+
+### Breaking Changes
+
+- `get_all_data` return keys changed: `"ratings"` split into `"ratings_continuous"` and `"ratings_sparse"`
+
+## v0.1.0
+
+Initial release.
+
+### Features
+
+- `HyperStudy` client with API key authentication (constructor arg or `HYPERSTUDY_API_KEY` env var)
+- Data retrieval methods: `get_events`, `get_recordings`, `get_chat`, `get_videochat`, `get_sync`, `get_ratings`, `get_components`, `get_participants`, `get_rooms`
+- `get_all_data` convenience method for fetching all data types for a single participant
+- Auto-pagination with `tqdm` progress bars (notebook and terminal)
+- Output format options: `"pandas"` (default), `"polars"`, `"dict"`
+- Experiment management: `list_experiments`, `get_experiment`, `get_experiment_config`, `create_experiment`, `update_experiment`, `delete_experiment`
+- Rich notebook display (`_repr_html_`) for experiment objects
+- Typed exceptions: `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `ServerError`
+- `health()` method for connection testing

{hyperstudy-0.2.3 → hyperstudy-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.2.3
+Version: 0.3.1
 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 → hyperstudy-0.3.1}/README.md

@@ -91,12 +91,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 → hyperstudy-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.2.3"
+version = "0.3.1"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"
@@ -28,6 +28,7 @@ dependencies = [
     "requests>=2.28.0",
     "pandas>=1.5.0",
     "tqdm>=4.60.0",
+    "pydantic>=2.5",
 ]
 
 [project.optional-dependencies]

hyperstudy-0.3.1/src/hyperstudy/__init__.py

@@ -0,0 +1,93 @@
+"""HyperStudy Python SDK — access experiment data from notebooks and scripts.
+
+Usage::
+
+    import hyperstudy
+
+    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
+from .client import HyperStudy
+from .exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    HyperStudyError,
+    NotFoundError,
+    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.3.0"
+
+__all__ = [
+    "HyperStudy",
+    "__version__",
+    # Exceptions
+    "HyperStudyError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ServerError",
+    "ValidationError",
+    # Enums
+    "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-0.2.3 → hyperstudy-0.3.1}/src/hyperstudy/_downloads.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
 from typing import Any
@@ -38,12 +39,12 @@ def build_filename(recording: dict[str, Any]) -> str:
 
 
 def download_file(url: str, dest: Path, timeout: int = 300) -> int:
-    """Stream-download *url* to *dest* and return bytes written.
+    """Stream-download *url* to *dest*; returns bytes written.
 
-    Verifies ``Content-Length`` (when the server provides it) against bytes
-    actually written. On any error — HTTP, mid-stream disconnect, or length
-    mismatch — the partial file on disk is removed so ``skip_existing``
-    logic won't mistake it for a complete download on retry.
+    Downloads to a temporary ``<dest>.part`` and atomically renames on success, so a
+    mid-stream failure (HTTP error, disconnect, length mismatch) removes only the temp
+    file and leaves any pre-existing complete file at ``dest`` intact. Verifies
+    ``Content-Length`` when provided.
     """
     resp = requests.get(url, stream=True, timeout=timeout)
     resp.raise_for_status()
@@ -57,20 +58,23 @@ def download_file(url: str, dest: Path, timeout: int = 300) -> int:
     else:
         expected = None
 
+    tmp = dest.with_name(dest.name + ".part")
     written = 0
-    # BaseException so Ctrl-C also cleans up, not just exceptions.
     try:
-        with open(dest, "wb") as fh:
+        with open(tmp, "wb") as fh:
             for chunk in resp.iter_content(chunk_size=_CHUNK_SIZE):
                 fh.write(chunk)
                 written += len(chunk)
-
         if expected is not None and written != expected:
             raise IOError(
                 f"Truncated download: wrote {written} of {expected} bytes for {dest.name}"
             )
+        os.replace(tmp, dest)   # atomic on the same filesystem
     except BaseException:
-        dest.unlink(missing_ok=True)
+        try:
+            tmp.unlink(missing_ok=True)   # remove only the temp; never the existing dest
+        except OSError:
+            pass
         raise
 
     return written

{hyperstudy-0.2.3 → hyperstudy-0.3.1}/src/hyperstudy/client.py

@@ -476,6 +476,19 @@ class HyperStudy(ExperimentMixin):
     # Recording downloads
     # ------------------------------------------------------------------
 
+    def _download_url_for(self, recording: dict[str, Any]) -> str | None:
+        """Resolve a directly-downloadable URL for a recording.
+
+        Prefers the auth'd mint endpoint (``downloadPath`` -> short-lived signed GCS
+        URL); falls back to a legacy absolute ``downloadUrl``/``url`` for old
+        GCS-only recordings.
+        """
+        download_path = recording.get("downloadPath")
+        if download_path:
+            body = self._transport.get(download_path)
+            return (body.get("data") or {}).get("url")
+        return get_download_url(recording)
+
     def download_recording(
         self,
         recording: dict[str, Any],
@@ -490,7 +503,7 @@ class HyperStudy(ExperimentMixin):
         Returns:
             Path to the downloaded file.
         """
-        url = get_download_url(recording)
+        url = self._download_url_for(recording)
         if not url:
             raise ValueError("Recording has no downloadUrl or url field")
 
@@ -564,27 +577,30 @@ class HyperStudy(ExperimentMixin):
 
         local_paths: list[str | None] = []
         statuses: list[str] = []
+        failed_count = 0
 
         for rec in tqdm(recordings, desc="Downloading recordings", disable=not progress):
             filename = build_filename(rec)
             dest = dest_dir / filename
 
-            url = get_download_url(rec)
-            if not url:
-                local_paths.append(None)
-                statuses.append("failed")
-                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
-                continue
-
+            # Check skip before resolving the URL (avoids minting a signed URL unnecessarily).
             if skip_existing and dest.exists():
                 expected_size = rec.get("fileSize")
-                # Require positive size match; missing size → re-download to
-                # avoid trusting a truncated file from a prior failed run.
-                if expected_size is not None and dest.stat().st_size == expected_size:
+                # dest is always a fully-written file (atomic rename), so skip when size is
+                # unknown OR matches; only re-download on a definite size mismatch.
+                if expected_size is None or dest.stat().st_size == expected_size:
                     local_paths.append(str(dest.resolve()))
                     statuses.append("skipped")
                     continue
 
+            url = self._download_url_for(rec)
+            if not url:
+                local_paths.append(None)
+                statuses.append("failed")
+                failed_count += 1
+                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
+                continue
+
             try:
                 download_file(url, dest)
                 local_paths.append(str(dest.resolve()))
@@ -592,11 +608,11 @@ class HyperStudy(ExperimentMixin):
             except Exception as exc:
                 local_paths.append(None)
                 statuses.append("failed")
+                failed_count += 1
                 warnings.warn(
                     f"Failed to download recording {rec.get('recordingId')}: {exc}"
                 )
 
-        failed_count = sum(1 for s in statuses if s == "failed")
         if failed_count:
             warnings.warn(
                 f"{failed_count}/{len(recordings)} recordings failed to download; "

hyperstudy-0.3.1/src/hyperstudy/experiments.py

@@ -0,0 +1,229 @@
+"""Experiment CRUD methods (mixed into HyperStudy via inheritance)."""
+
+from __future__ import annotations
+
+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
+from .models import camelize_wire
+
+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 = camelize_wire(experiment)
+    else:
+        raise TypeError(
+            f"experiment must be an Experiment or dict, got {type(experiment).__name__}"
+        )
+    for key, value in overrides.items():
+        ck = to_camel(key)
+        payload[ck] = camelize_wire(value, _parent_key=ck)
+    return payload
+
+
+class ExperimentMixin:
+    """Methods for experiment management. Mixed into the main client."""
+
+    _transport: HttpTransport
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def list_experiments(
+        self,
+        *,
+        search: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """List experiments accessible to the authenticated user.
+
+        Args:
+            search: Filter experiments by name/description substring.
+            limit: Max experiments to return. ``None`` fetches all pages.
+            offset: Starting offset for pagination.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+            progress: Show progress bar when paginating.
+
+        Returns:
+            DataFrame or list of dicts depending on *output*.
+        """
+        params: dict[str, Any] = {"offset": offset}
+        if search:
+            params["search"] = search
+
+        if limit is not None:
+            params["limit"] = limit
+            body = self._transport.get("experiments", params=params)
+            data = body.get("data", [])
+        else:
+            data, _ = fetch_all_pages(
+                self._transport,
+                "experiments",
+                params=params,
+                page_size=50,
+                progress=progress,
+            )
+
+        return self._convert_output(data, output)
+
+    def get_experiment(self, experiment_id: str) -> ExperimentInfo:
+        """Get a single experiment with enriched metadata.
+
+        Returns:
+            An :class:`ExperimentInfo` object (dict-like, with ``_repr_html_``).
+        """
+        body = self._transport.get(f"experiments/{experiment_id}")
+        data = body.get("data", [])
+        record = data[0] if isinstance(data, list) and data else data
+        return ExperimentInfo(record)
+
+    def get_experiment_config(self, experiment_id: str) -> dict[str, Any]:
+        """Get raw experiment config (lightweight, no enrichment)."""
+        body = self._transport.get(f"experiments/{experiment_id}/config")
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    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:
+            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`.
+        """
+        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,
+        *,
+        experiment: "Experiment | None" = None,
+        **kwargs,
+    ) -> dict[str, Any]:
+        """Update an experiment.
+
+        Args:
+            experiment_id: ID of the experiment to update.
+            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.
+        """
+        payload = _build_experiment_payload(experiment, **kwargs)
+        if not payload:
+            raise ValueError(
+                "update_experiment requires at least one field to update "
+                "(pass experiment=... or keyword fields)."
+            )
+        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
+
+    def delete_experiment(
+        self, experiment_id: str, *, skip_data_check: bool = False
+    ) -> None:
+        """Delete (soft-delete) an experiment.
+
+        Args:
+            experiment_id: ID of the experiment to delete.
+            skip_data_check: If True, skip the confirmation check for experiments
+                with collected data.
+        """
+        params = {}
+        if skip_data_check:
+            params["skipDataCheck"] = "true"
+        self._transport.delete(f"experiments/{experiment_id}", params=params)