hyperstudy 0.1.0__py3-none-any.whl

hyperstudy/__init__.py

@@ -0,0 +1,38 @@
+"""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")
+"""
+
+from ._types import DataType, RatingKind, Scope
+from .client import HyperStudy
+from .exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    HyperStudyError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HyperStudy",
+    "__version__",
+    # Exceptions
+    "HyperStudyError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ServerError",
+    "ValidationError",
+    # Enums
+    "Scope",
+    "DataType",
+    "RatingKind",
+]

hyperstudy/_dataframe.py

@@ -0,0 +1,68 @@
+"""DataFrame conversion for API response data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+
+def _post_process(df: pd.DataFrame) -> pd.DataFrame:
+    """Shared post-processing for pandas DataFrames.
+
+    * Parses timestamp columns to datetime.
+    * Computes ``onset_sec`` from ``onset`` (ms -> s).
+    """
+    if df.empty:
+        return df
+
+    # Parse common timestamp columns
+    for col in ("timestamp", "startTime", "endTime", "createdAt", "updatedAt"):
+        if col in df.columns:
+            df[col] = pd.to_datetime(df[col], errors="coerce")
+
+    # Compute onset in seconds
+    if "onset" in df.columns:
+        df["onset_sec"] = pd.to_numeric(df["onset"], errors="coerce") / 1000.0
+
+    return df
+
+
+def to_pandas(data: list[dict[str, Any]]) -> pd.DataFrame:
+    """Convert API response data to a pandas DataFrame with post-processing."""
+    if not data:
+        return pd.DataFrame()
+    df = pd.DataFrame(data)
+    return _post_process(df)
+
+
+def to_polars(data: list[dict[str, Any]]):
+    """Convert API response data to a polars DataFrame.
+
+    Raises ImportError with a helpful message if polars is not installed.
+    """
+    try:
+        import polars as pl
+    except ImportError:
+        raise ImportError(
+            "polars is not installed. Install it with: pip install hyperstudy[polars]"
+        ) from None
+
+    if not data:
+        return pl.DataFrame()
+
+    df = pl.DataFrame(data)
+
+    # Parse timestamps
+    for col in ("timestamp", "startTime", "endTime", "createdAt", "updatedAt"):
+        if col in df.columns:
+            try:
+                df = df.with_columns(pl.col(col).str.to_datetime(strict=False).alias(col))
+            except Exception:
+                pass  # Column may already be datetime or have unexpected format
+
+    # Compute onset_sec
+    if "onset" in df.columns:
+        df = df.with_columns((pl.col("onset").cast(pl.Float64) / 1000.0).alias("onset_sec"))
+
+    return df

hyperstudy/_display.py

@@ -0,0 +1,64 @@
+"""Rich display helpers for Jupyter and marimo notebooks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ExperimentInfo:
+    """Wrapper around an experiment dict with ``_repr_html_`` for notebooks."""
+
+    def __init__(self, data: dict[str, Any]):
+        self._data = data
+
+    def __getitem__(self, key):
+        return self._data[key]
+
+    def __contains__(self, key):
+        return key in self._data
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    def __repr__(self):
+        name = self._data.get("name", "Unknown")
+        eid = self._data.get("id", "?")
+        return f"Experiment({eid!r}, name={name!r})"
+
+    def _repr_html_(self) -> str:
+        d = self._data
+        rows = ""
+        display_fields = [
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Description", "description"),
+            ("Owner", "ownerEmail"),
+            ("Rooms", "roomCount"),
+            ("Participants", "participantCount"),
+            ("Created", "createdAt"),
+            ("Updated", "updatedAt"),
+        ]
+        for label, key in display_fields:
+            val = d.get(key)
+            if val is not None:
+                rows += (
+                    f"<tr><th style='text-align:left;padding:4px 12px 4px 0'>"
+                    f"{label}</th><td style='padding:4px 0'>{val}</td></tr>"
+                )
+        return (
+            "<div style='font-family:system-ui,sans-serif;max-width:600px'>"
+            f"<h4 style='margin:0 0 8px'>Experiment: {d.get('name', '?')}</h4>"
+            f"<table style='border-collapse:collapse'>{rows}</table></div>"
+        )

hyperstudy/_http.py

@@ -0,0 +1,128 @@
+"""Low-level HTTP transport wrapping requests.Session."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    HyperStudyError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+_STATUS_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+}
+
+
+class HttpTransport:
+    """Thin wrapper around ``requests.Session`` for the HyperStudy API.
+
+    * Sets ``X-API-Key`` header on every request.
+    * Parses the standard ``{status, metadata, data}`` response envelope.
+    * Maps HTTP error codes to typed exceptions.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.hyperstudy.io/api/v3",
+        timeout: int = 30,
+    ):
+        resolved_key = api_key or os.environ.get("HYPERSTUDY_API_KEY")
+        if not resolved_key:
+            raise AuthenticationError(
+                "No API key provided. Pass api_key= or set the HYPERSTUDY_API_KEY "
+                "environment variable.",
+                code="MISSING_API_KEY",
+                status_code=401,
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": resolved_key,
+                "Accept": "application/json",
+            }
+        )
+
+    # ------------------------------------------------------------------
+    # Public helpers
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: dict[str, Any] | None = None) -> dict:
+        return self._request("POST", path, json=json)
+
+    def put(self, path: str, json: dict[str, Any] | None = None) -> dict:
+        return self._request("PUT", path, json=json)
+
+    def delete(self, path: str, params: dict[str, Any] | None = None) -> dict:
+        return self._request("DELETE", path, params=params)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        kwargs.setdefault("timeout", self.timeout)
+
+        resp = self._session.request(method, url, **kwargs)
+        return self._handle_response(resp)
+
+    @staticmethod
+    def _handle_response(resp: requests.Response) -> dict:
+        """Parse the JSON envelope and raise on errors."""
+        try:
+            body = resp.json()
+        except ValueError:
+            if resp.status_code >= 500:
+                raise ServerError(
+                    f"Server returned {resp.status_code} with non-JSON body",
+                    code="SERVER_ERROR",
+                    status_code=resp.status_code,
+                )
+            raise HyperStudyError(
+                f"Unexpected non-JSON response ({resp.status_code})",
+                status_code=resp.status_code,
+            )
+
+        # API-level error envelope: {"status": "error", "error": {...}}
+        if body.get("status") == "error":
+            err = body.get("error", {})
+            message = err.get("message", resp.reason or "Unknown error")
+            code = err.get("code", "UNKNOWN")
+            details = err.get("details")
+            exc_cls = _STATUS_MAP.get(resp.status_code, HyperStudyError)
+            if resp.status_code >= 500:
+                exc_cls = ServerError
+            raise exc_cls(
+                message, code=code, status_code=resp.status_code, details=details
+            )
+
+        # Non-2xx without error envelope
+        if not resp.ok:
+            exc_cls = _STATUS_MAP.get(resp.status_code, HyperStudyError)
+            if resp.status_code >= 500:
+                exc_cls = ServerError
+            raise exc_cls(
+                resp.reason or f"HTTP {resp.status_code}",
+                status_code=resp.status_code,
+            )
+
+        return body

hyperstudy/_pagination.py

@@ -0,0 +1,61 @@
+"""Auto-pagination with progress bars for multi-page fetches."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tqdm.auto import tqdm
+
+from ._http import HttpTransport
+
+
+def fetch_all_pages(
+    transport: HttpTransport,
+    path: str,
+    params: dict[str, Any] | None = None,
+    *,
+    page_size: int = 1000,
+    progress: bool = True,
+) -> tuple[list[dict], dict]:
+    """Fetch every page of a paginated endpoint.
+
+    Returns:
+        (all_data, last_metadata) — the combined list plus the metadata
+        dict from the final page (useful for inspecting total counts, etc.).
+    """
+    params = dict(params or {})
+    params["limit"] = page_size
+    params.setdefault("offset", 0)
+
+    # First request to learn total
+    body = transport.get(path, params=params)
+    metadata = body.get("metadata", {})
+    pagination = metadata.get("pagination", {})
+    total = pagination.get("total", 0)
+    all_data: list[dict] = body.get("data", [])
+
+    has_more = pagination.get("hasMore", False)
+
+    bar = None
+    if progress and total > page_size:
+        bar = tqdm(total=total, desc="Fetching", unit=" rows", initial=len(all_data))
+
+    while has_more:
+        params["offset"] = pagination.get("nextOffset", params["offset"] + page_size)
+
+        body = transport.get(path, params=params)
+        metadata = body.get("metadata", {})
+        pagination = metadata.get("pagination", {})
+
+        page_data = body.get("data", [])
+        all_data.extend(page_data)
+        has_more = pagination.get("hasMore", False)
+
+        if bar is not None:
+            bar.update(len(page_data))
+
+    if bar is not None:
+        bar.update(bar.total - bar.n)  # snap to 100 %
+        bar.close()
+
+    return all_data, metadata

hyperstudy/_types.py

@@ -0,0 +1,30 @@
+"""Enums for the HyperStudy API.
+
+All enums inherit from (str, Enum) so users can pass either
+Scope.EXPERIMENT or the plain string "experiment".
+"""
+
+from enum import Enum
+
+
+class Scope(str, Enum):
+    EXPERIMENT = "experiment"
+    ROOM = "room"
+    PARTICIPANT = "participant"
+
+
+class DataType(str, Enum):
+    EVENTS = "events"
+    RECORDINGS = "recordings"
+    CHAT = "chat"
+    VIDEOCHAT = "videochat"
+    SYNC = "sync"
+    RATINGS = "ratings"
+    COMPONENTS = "components"
+    PARTICIPANTS = "participants"
+    ROOMS = "rooms"
+
+
+class RatingKind(str, Enum):
+    CONTINUOUS = "continuous"
+    SPARSE = "sparse"

hyperstudy/client.py

@@ -0,0 +1,368 @@
+"""Main HyperStudy client — the primary entry point for the SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._dataframe import to_pandas, to_polars
+from ._http import HttpTransport
+from ._pagination import fetch_all_pages
+from ._types import Scope
+from .experiments import ExperimentMixin
+
+
+class HyperStudy(ExperimentMixin):
+    """Client for the HyperStudy API v3.
+
+    Args:
+        api_key: Your API key (``hst_live_...`` or ``hst_test_...``).
+            Also reads the ``HYPERSTUDY_API_KEY`` environment variable.
+        base_url: API base URL. Defaults to the production endpoint.
+        timeout: Request timeout in seconds.
+
+    Example::
+
+        import hyperstudy
+
+        hs = hyperstudy.HyperStudy(api_key="hst_live_...")
+        events = hs.get_events("experiment_id")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = "https://api.hyperstudy.io/api/v3",
+        timeout: int = 30,
+    ):
+        self._transport = HttpTransport(
+            api_key=api_key, base_url=base_url, timeout=timeout
+        )
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        """Check API connectivity and version."""
+        return self._transport.get("health")
+
+    # ------------------------------------------------------------------
+    # Data retrieval — one method per data type
+    # ------------------------------------------------------------------
+
+    def get_events(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        category: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch experiment events.
+
+        Args:
+            scope_id: ID of the experiment, room, or participant.
+            scope: ``"experiment"``, ``"room"``, or ``"participant"``.
+            room_id: Required when ``scope="participant"``.
+            start_time: ISO 8601 start filter.
+            end_time: ISO 8601 end filter.
+            category: Event category filter.
+            sort: Sort field (e.g. ``"onset"``, ``"timestamp"``).
+            order: ``"asc"`` or ``"desc"``.
+            limit: Max records. ``None`` fetches all pages.
+            offset: Starting offset.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+            progress: Show progress bar when paginating.
+        """
+        return self._fetch_data(
+            "events", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            category=category, sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_recordings(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch video/audio recording metadata."""
+        return self._fetch_data(
+            "recordings", scope_id,
+            scope=scope, room_id=room_id,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_chat(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch text chat messages."""
+        return self._fetch_data(
+            "chat", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_videochat(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch LiveKit video chat connection data."""
+        return self._fetch_data(
+            "videochat", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_sync(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        aggregation_window: int | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch media synchronization metrics."""
+        extra: dict[str, Any] = {}
+        if aggregation_window is not None:
+            extra["aggregationWindow"] = aggregation_window
+        return self._fetch_data(
+            "sync", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+            **extra,
+        )
+
+    def get_ratings(
+        self,
+        scope_id: str,
+        *,
+        kind: str = "continuous",
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch rating data.
+
+        Args:
+            kind: ``"continuous"`` (slider) or ``"sparse"`` (button-press).
+            *: All other args are the same as :meth:`get_events`.
+        """
+        return self._fetch_data(
+            f"ratings/{kind}", scope_id,
+            scope=scope, room_id=room_id,
+            start_time=start_time, end_time=end_time,
+            sort=sort, order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_components(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch component response data."""
+        return self._fetch_data(
+            "components", scope_id,
+            scope=scope, room_id=room_id,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_participants(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch participant data."""
+        return self._fetch_data(
+            "participants", scope_id,
+            scope=scope, room_id=room_id,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    def get_rooms(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch room/session data."""
+        return self._fetch_data(
+            "rooms", scope_id,
+            scope=scope,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
+    # ------------------------------------------------------------------
+    # Convenience: all data for a participant
+    # ------------------------------------------------------------------
+
+    def get_all_data(
+        self,
+        participant_id: str,
+        *,
+        room_id: str,
+        output: str = "pandas",
+    ) -> dict:
+        """Fetch all data types for one participant in a room.
+
+        Returns:
+            Dict mapping data type names to DataFrames (or dicts).
+        """
+        common = dict(scope="participant", room_id=room_id, output=output, progress=False)
+        return {
+            "events": self.get_events(participant_id, **common),
+            "recordings": self.get_recordings(participant_id, **common),
+            "chat": self.get_chat(participant_id, **common),
+            "videochat": self.get_videochat(participant_id, **common),
+            "sync": self.get_sync(participant_id, **common),
+            "ratings": self.get_ratings(participant_id, kind="continuous", **common),
+            "components": self.get_components(participant_id, **common),
+        }
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _fetch_data(
+        self,
+        data_type: str,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        room_id: str | None = None,
+        start_time: str | None = None,
+        end_time: str | None = None,
+        category: str | None = None,
+        sort: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+        **extra_params,
+    ):
+        """Generic data-fetching logic shared by all ``get_*`` methods."""
+        scope_val = Scope(scope)
+        path = f"data/{data_type}/{scope_val.value}/{scope_id}"
+
+        params: dict[str, Any] = {"offset": offset}
+        if room_id:
+            params["roomId"] = room_id
+        if start_time:
+            params["startTime"] = start_time
+        if end_time:
+            params["endTime"] = end_time
+        if category:
+            params["category"] = category
+        if sort:
+            params["sort"] = sort
+        if order:
+            params["order"] = order
+        params.update(extra_params)
+
+        # Single page or all pages
+        if limit is not None:
+            params["limit"] = limit
+            body = self._transport.get(path, params=params)
+            data = body.get("data", [])
+        else:
+            data, _ = fetch_all_pages(
+                self._transport, path, params=params, progress=progress
+            )
+
+        return self._convert_output(data, output)
+
+    @staticmethod
+    def _convert_output(data: list[dict], output: str):
+        """Convert raw dicts to the requested output format."""
+        if output == "dict":
+            return data
+        if output == "polars":
+            return to_polars(data)
+        # Default: pandas
+        return to_pandas(data)

hyperstudy/exceptions.py

@@ -0,0 +1,58 @@
+"""Typed exceptions for HyperStudy API errors."""
+
+
+class HyperStudyError(Exception):
+    """Base exception for all HyperStudy API errors.
+
+    Attributes:
+        message: Human-readable error description.
+        code: Machine-readable error code from the API (e.g. 'VALIDATION_ERROR').
+        status_code: HTTP status code.
+        details: Optional dict with additional error context.
+    """
+
+    def __init__(self, message, *, code=None, status_code=None, details=None):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details or {}
+
+    def __repr__(self):
+        parts = [f"HyperStudyError({self.message!r}"]
+        if self.code:
+            parts[0] = f"{type(self).__name__}({self.message!r}"
+            parts.append(f"code={self.code!r}")
+        if self.status_code:
+            parts.append(f"status_code={self.status_code}")
+        return ", ".join(parts) + ")"
+
+
+class AuthenticationError(HyperStudyError):
+    """Raised on 401 — invalid or missing API key."""
+
+    pass
+
+
+class ForbiddenError(HyperStudyError):
+    """Raised on 403 — valid key but insufficient scopes or access."""
+
+    pass
+
+
+class NotFoundError(HyperStudyError):
+    """Raised on 404 — resource does not exist."""
+
+    pass
+
+
+class ValidationError(HyperStudyError):
+    """Raised on 400 — invalid request parameters."""
+
+    pass
+
+
+class ServerError(HyperStudyError):
+    """Raised on 5xx — server-side failure."""
+
+    pass

hyperstudy/experiments.py

@@ -0,0 +1,125 @@
+"""Experiment CRUD methods (mixed into HyperStudy via inheritance)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._display import ExperimentInfo
+from ._http import HttpTransport
+from ._pagination import fetch_all_pages
+
+
+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, *, name: str, **kwargs) -> ExperimentInfo:
+        """Create a new experiment.
+
+        Args:
+            name: Experiment name (required).
+            **kwargs: Additional fields (config, states, roles, description, etc.).
+
+        Returns:
+            The created :class:`ExperimentInfo`.
+        """
+        payload = {"name": name, **kwargs}
+        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]:
+        """Update an experiment.
+
+        Args:
+            experiment_id: ID of the experiment to update.
+            **kwargs: Fields to update (name, config, states, etc.).
+
+        Returns:
+            Update confirmation dict.
+        """
+        body = self._transport.put(f"experiments/{experiment_id}", json=kwargs)
+        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)

hyperstudy-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: hyperstudy
+Version: 0.1.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
+Project-URL: Repository, https://github.com/ljchang/hyperstudy-pythonsdk
+Project-URL: Issues, https://github.com/ljchang/hyperstudy-pythonsdk/issues
+Author-email: Luke Chang <luke.j.chang@dartmouth.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20.0; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# hyperstudy
+
+Python SDK for the [HyperStudy](https://hyperstudy.io) experiment platform API. Designed for researchers working in Jupyter, marimo, or Python scripts.
+
+## Installation
+
+```bash
+pip install hyperstudy
+```
+
+For polars support:
+
+```bash
+pip install hyperstudy[polars]
+```
+
+## Quick Start
+
+```python
+import hyperstudy
+
+hs = hyperstudy.HyperStudy(api_key="hst_live_...")
+# Or set the HYPERSTUDY_API_KEY environment variable
+
+# Fetch events as a pandas DataFrame
+events = hs.get_events("your_experiment_id")
+
+# Room-scoped data
+events = hs.get_events("room_id", scope="room")
+
+# Participant-scoped data
+events = hs.get_events("participant_id", scope="participant", room_id="room_id")
+```
+
+## Data Types
+
+All data retrieval methods follow the same pattern:
+
+```python
+events      = hs.get_events("exp_id")
+recordings  = hs.get_recordings("exp_id")
+chat        = hs.get_chat("exp_id")
+videochat   = hs.get_videochat("exp_id")
+sync        = hs.get_sync("exp_id")
+ratings     = hs.get_ratings("exp_id", kind="continuous")
+components  = hs.get_components("exp_id")
+participants = hs.get_participants("exp_id")
+rooms       = hs.get_rooms("exp_id")
+```
+
+### Output Formats
+
+```python
+df_pandas = hs.get_events("exp_id")                      # pandas (default)
+df_polars = hs.get_events("exp_id", output="polars")     # polars
+raw       = hs.get_events("exp_id", output="dict")       # list[dict]
+```
+
+### Filtering
+
+```python
+events = hs.get_events(
+    "exp_id",
+    start_time="2024-01-01T10:00:00Z",
+    end_time="2024-01-01T12:00:00Z",
+    category="component",
+    sort="onset",
+    limit=100,
+)
+```
+
+### Auto-Pagination
+
+When `limit` is not set, all pages are fetched automatically with a progress bar:
+
+```python
+all_events = hs.get_events("exp_id")  # fetches all pages
+```
+
+## Experiment Management
+
+```python
+# List experiments
+experiments = hs.list_experiments()
+
+# Get details (with rich display in notebooks)
+exp = hs.get_experiment("exp_id")
+
+# Create / update / delete
+new_exp = hs.create_experiment(name="My Study", description="...")
+hs.update_experiment("exp_id", name="Updated Name")
+hs.delete_experiment("exp_id")
+```
+
+## All Data for a Participant
+
+```python
+data = hs.get_all_data("participant_id", room_id="room_id")
+# Returns: {"events": DataFrame, "recordings": DataFrame, "chat": DataFrame, ...}
+```
+
+## API Key
+
+Generate an API key from the HyperStudy dashboard under Settings. Keys follow the format `hst_{environment}_{key}` and are passed via the `X-API-Key` header.
+
+## Documentation
+
+Full documentation: [docs.hyperstudy.io/developers/python-sdk](https://docs.hyperstudy.io/developers/python-sdk)
+
+## Development
+
+```bash
+git clone https://github.com/ljchang/hyperstudy-pythonsdk.git
+cd hyperstudy-pythonsdk
+pip install -e ".[dev,polars]"
+pytest --cov=hyperstudy
+ruff check src/
+```
+
+## License
+
+MIT

hyperstudy-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+hyperstudy/__init__.py,sha256=HG3ZO_xJEDLMDvmAdv4DtADVxph7yWCPS1LqJUs9ebQ,733
+hyperstudy/_dataframe.py,sha256=gOHPE6RRoZ_a4Qkdl9XykkGTqH6I7P6pedKoFuAvKek,1966
+hyperstudy/_display.py,sha256=5svr4NFOUJkVif57-xJzrXNOSdA5O9tKesu8UhE_jYo,1896
+hyperstudy/_http.py,sha256=PjDaS1gMENJFUk2WxzN9yyEppO-tITkQnUVGHAj3ocU,4242
+hyperstudy/_pagination.py,sha256=Fdr2nW84r6NtXiYQs5jyJEUOjFvXl-RclpDIi-SPDlM,1738
+hyperstudy/_types.py,sha256=22JTOlM68eGJ4hg4OH-oT-hmARG2CgbhnERJ5hGxHk8,614
+hyperstudy/client.py,sha256=0dw7dfFQ7bv1rIdSa7STFX4VHJpuFZ6h7HOWGO5uiU0,11633
+hyperstudy/exceptions.py,sha256=z_1Ngiq-RU-1yyDI_JqvQ5CvYm2jQ_lyJ9TUbqUKKv8,1529
+hyperstudy/experiments.py,sha256=BHNf-ctKUA9uzy8Kya11nIyHPrsmOslqC_IJ5t4LxKA,4372
+hyperstudy-0.1.0.dist-info/METADATA,sha256=sQ4zPFcGv1tMruM37yMLXWkqfF9IORAJClVwxmtyrY0,4176
+hyperstudy-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hyperstudy-0.1.0.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
+hyperstudy-0.1.0.dist-info/RECORD,,

hyperstudy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hyperstudy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luke Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.