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

hyperstudy/__init__.py

@@ -33,17 +33,24 @@ from .models import (
     AgentConfig,
     ComponentType,
     DisconnectTimeout,
+    EngineTurnDetection,
     Experiment,
+    ExperimenterMessageStyle,
     FocusComponent,
     GlobalComponentType,
     Guardrails,
     InstructionsPage,
     Persona,
+    PersonaChat,
+    PersonaVoice,
     PostExperimentQuestionnaire,
     PromptLayer,
+    RealtimeVoice,
     Role,
     State,
     TransitionRules,
+    VoiceTranscription,
+    VoiceTurnTaking,
     WaitingRoomConfig,
     likert_scale,
     multiple_choice,
@@ -56,7 +63,7 @@ from .models import (
     waiting,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "HyperStudy",
@@ -82,7 +89,14 @@ __all__ = [
     "AgentConfig",
     "PromptLayer",
     "Persona",
+    "PersonaVoice",
+    "RealtimeVoice",
+    "PersonaChat",
     "Guardrails",
+    "VoiceTurnTaking",
+    "EngineTurnDetection",
+    "VoiceTranscription",
+    "ExperimenterMessageStyle",
     "TransitionRules",
     "WaitingRoomConfig",
     "DisconnectTimeout",

hyperstudy/_http.py

@@ -25,6 +25,23 @@ _STATUS_MAP = {
 }
 
 
+def single_record(body: dict) -> dict:
+    """Return the one record of a single-object response.
+
+    The v3 envelope always carries ``data`` as an array: a route that responds
+    with one object (a persona, a created deployment, a signed download URL)
+    arrives as ``[obj]``.
+    """
+    data = body.get("data")
+    if not isinstance(data, list):
+        raise HyperStudyError(
+            f"Unexpected response: expected 'data' to be an array, got {type(data).__name__}"
+        )
+    if not data or data[0] is None:
+        raise HyperStudyError("Unexpected response: the server returned no record")
+    return data[0]
+
+
 class HttpTransport:
     """Thin wrapper around ``requests.Session`` for the HyperStudy API.
 

hyperstudy/_types.py

@@ -17,9 +17,11 @@ class DataType(str, Enum):
     EVENTS = "events"
     RECORDINGS = "recordings"
     CHAT = "chat"
+    VOICE = "voice"
     VIDEOCHAT = "videochat"
     SYNC = "sync"
     RATINGS = "ratings"
+    EYETRACKING = "eyetracking"
     COMPONENTS = "components"
     PARTICIPANTS = "participants"
     ROOMS = "rooms"

hyperstudy/client.py

@@ -10,7 +10,7 @@ from tqdm.auto import tqdm
 
 from ._dataframe import to_pandas, to_polars
 from ._downloads import build_filename, download_file, get_download_url
-from ._http import HttpTransport
+from ._http import HttpTransport, single_record
 from ._pagination import fetch_all_pages
 from ._types import Scope
 from .exceptions import HyperStudyError
@@ -146,6 +146,69 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             output=output, progress=progress,
         )
 
+    def get_voice(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        deployment_id: str | None = None,
+        room_id: str | None = None,
+        include_context: bool = True,
+        order: str | None = None,
+        limit: int | None = None,
+        offset: int = 0,
+        output: str = "pandas",
+        progress: bool = True,
+    ):
+        """Fetch voice agent conversations, one flat row per voice event.
+
+        ``kind`` says what a row is:
+
+        - ``utterance``: a speech turn that reached the room. ``speaker`` is
+          ``participant`` or ``agent``; ``transcript`` is what was said (for an
+          agent, the generated text).
+        - ``discarded``: a false start, or an agent reply dropped before any
+          of it was heard.
+        - ``response``: an agent reply that acted without speaking, such as
+          answering an on-screen question (see ``toolCalls``).
+        - ``context``: what the voice engine was told (``contextKind``,
+          ``contextText``).
+        - ``connection``: the engine connection was lost, restored or failed
+          (``connectionEvent``); the study was paused meanwhile.
+
+        Agent rows also report how much of the generated speech the room
+        heard (``heardMs``, ``generatedMs``, ``truncated``) and
+        ``responseLatencyMs``, from the participant's end of speech to the
+        agent's first audio.
+
+        Participant scope returns only that participant's own events. For a
+        whole conversation, every speaker plus what the engine was told, use
+        ``scope="room"``. Requires the ``read:events`` scope.
+
+        Args:
+            scope_id: ID of the experiment, room, or participant.
+            scope: ``"experiment"``, ``"room"``, or ``"participant"``.
+            deployment_id: Filter by deployment (experiment scope only).
+            room_id: Narrow a participant's events to one room.
+            include_context: Include ``context`` rows (default True).
+            order: ``"asc"`` (default) or ``"desc"`` by time.
+            limit: Max records. ``None`` fetches all pages.
+            offset: Starting offset.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+            progress: Show progress bar when paginating.
+        """
+        extra: dict[str, Any] = {}
+        if not include_context:
+            extra["includeContext"] = "false"
+        return self._fetch_data(
+            "voice", scope_id,
+            scope=scope, deployment_id=deployment_id, room_id=room_id,
+            order=order,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+            **extra,
+        )
+
     def get_videochat(
         self,
         scope_id: str,
@@ -235,6 +298,35 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             output=output, progress=progress,
         )
 
+    def get_eyetracking(
+        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 eye-tracking gaze data.
+
+        Args:
+            scope_id: ID of the experiment, room, or participant.
+            scope: ``"experiment"``, ``"room"``, or ``"participant"``.
+            room_id: Required when ``scope="participant"``.
+            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(
+            "eyetracking", scope_id,
+            scope=scope, room_id=room_id,
+            limit=limit, offset=offset,
+            output=output, progress=progress,
+        )
+
     def get_components(
         self,
         scope_id: str,
@@ -242,17 +334,41 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         scope: str = "experiment",
         deployment_id: str | None = None,
         room_id: str | None = None,
+        component_type: str | None = None,
+        state_id: str | None = None,
+        completed: bool | 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 component response data."""
+        """Fetch component response data.
+
+        Args:
+            component_type: Only this component type (e.g. ``"vasrating"``).
+            state_id: Only components shown in this state.
+            completed: Only completed (True) or uncompleted (False) components.
+            *: All other args are the same as :meth:`get_events`.
+        """
+        extra: dict[str, Any] = {}
+        if component_type:
+            extra["componentType"] = component_type
+        if state_id:
+            extra["stateId"] = state_id
+        if completed is not None:
+            extra["completed"] = "true" if completed else "false"
         return self._fetch_data(
             "components", scope_id,
             scope=scope, deployment_id=deployment_id, 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_participants(
@@ -262,17 +378,32 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         scope: str = "experiment",
         deployment_id: str | None = None,
         room_id: str | None = None,
+        completion_code: 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 participant data."""
+        """Fetch participant data.
+
+        Args:
+            completion_code: Only participants with this outcome: ``SUCCESS``,
+                ``TIMEOUT``, ``TECHNICAL``, ``NOCONSENT``, ``ABANDONED``, or the
+                derived ``IN_PROGRESS`` / ``COMPLETED_NO_CODE``.
+            *: All other args are the same as :meth:`get_events`.
+        """
+        extra: dict[str, Any] = {}
+        if completion_code:
+            extra["completionCode"] = completion_code
         return self._fetch_data(
             "participants", scope_id,
             scope=scope, deployment_id=deployment_id, room_id=room_id,
+            sort=sort, order=order,
             limit=limit, offset=offset,
             output=output, progress=progress,
+            **extra,
         )
 
     def get_rooms(
@@ -281,19 +412,98 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         *,
         scope: str = "experiment",
         deployment_id: 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 room/session data."""
+        """Fetch room/session data.
+
+        Each room reports ``completionReason`` (how it ended: ``completed``,
+        or an end reason such as ``ABANDONED`` or ``disconnect_timeout``) and
+        ``agentStartFailures`` (why its agents could not start, by role).
+        """
         return self._fetch_data(
             "rooms", scope_id,
             scope=scope, deployment_id=deployment_id,
+            sort=sort, order=order,
             limit=limit, offset=offset,
             output=output, progress=progress,
         )
 
+    def get_variables(
+        self,
+        room_id: str,
+        *,
+        output: str = "pandas",
+    ):
+        """Fetch the reconstructed shared-variable timeline for a room.
+
+        Returns a dict with four keys:
+
+        - ``writes`` — the time-ordered write log (one row per variable
+          write: seeded constant, human component response, or agent
+          submit-response, tagged with source and persisted flag), converted
+          per ``output``
+        - ``timeline`` — the derived per-state forward-filled variable
+          snapshot matrix, converted per ``output``
+        - ``variable_names`` — ordered list of every variable seen
+        - ``matrix_columns`` — ordered column set of the timeline matrix
+        - ``dropped_writes`` — writes that failed the server's ground-truth
+          cross-checks (a bug signal; empty is the healthy state)
+        - ``mode`` — the reconstruction mode the server processor ran in
+
+        Args:
+            room_id: Room ID.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``
+                for the tabular values.
+        """
+        body = self._transport.get(f"data/variables/room/{room_id}")
+        metadata = body.get("metadata") or {}
+        return {
+            "writes": self._convert_output(body.get("data", []), output),
+            "timeline": self._convert_output(metadata.get("timeline") or [], output),
+            "variable_names": metadata.get("variableNames") or [],
+            "matrix_columns": metadata.get("matrixColumns") or [],
+            "dropped_writes": metadata.get("droppedWrites") or [],
+            "mode": metadata.get("mode"),
+        }
+
+    def get_counts(
+        self,
+        participant_id: str,
+        room_id: str,
+    ) -> dict[str, Any]:
+        """Fetch per-data-type document counts for a participant in a room.
+
+        Cheap count queries grouped by data type — useful for checking
+        which data types exist before fetching them.
+
+        Args:
+            participant_id: Participant ID.
+            room_id: Room ID.
+
+        Returns:
+            Dict with ``counts`` and ``hasData`` keyed by data type.
+        """
+        body = self._transport.get(
+            f"data/counts/participant/{participant_id}", params={"roomId": room_id}
+        )
+        return single_record(body)
+
+    def check_data_access(self, experiment_id: str) -> dict[str, bool]:
+        """Check whether you may view and export an experiment's data.
+
+        Returns no data, so it is a cheap check before a large fetch.
+
+        Returns:
+            ``{"canView": bool, "canExport": bool}``
+        """
+        body = self._transport.get(f"data/check-access/experiment/{experiment_id}")
+        return {"canView": body["canView"], "canExport": body["canExport"]}
+
     # ------------------------------------------------------------------
     # Convenience: category-filtered events
     # ------------------------------------------------------------------
@@ -423,8 +633,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             Deployment dict.
         """
         body = self._transport.get(f"deployments/{deployment_id}")
-        data = body.get("data", [])
-        return data[0] if isinstance(data, list) and data else data
+        return single_record(body)
 
     def get_deployment_sessions(
         self,
@@ -483,12 +692,12 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         body = self._transport.post(
             "deployments", json={"experimentId": experiment_id, "config": merged}
         )
-        return body.get("data", {})
+        return single_record(body)
 
     def get_agent_spend(self, deployment_id: str) -> dict[str, Any]:
         """Total + per-room agent LLM spend for an agent-only deployment."""
         body = self._transport.get(f"deployments/{deployment_id}/agent-spend")
-        return body.get("data", {})
+        return single_record(body)
 
     def run_more(
         self, deployment_id: str, *, rooms: int, budget_usd: float
@@ -508,7 +717,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             f"deployments/{deployment_id}/run-more",
             json={"rooms": rooms, "budgetUsd": budget_usd},
         )
-        return body.get("data", {})
+        return single_record(body)
 
     def stop_room(self, deployment_id: str, room_id: str) -> None:
         """Force-end a running agent room."""
@@ -519,7 +728,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         body = self._transport.post(
             f"deployments/{deployment_id}/rooms/{room_id}/retry"
         )
-        return body.get("data", {})
+        return single_record(body)
 
     # ------------------------------------------------------------------
     # Agent data — decisions and run manifests
@@ -591,7 +800,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         body = self._transport.get(
             f"data/agent-decisions/room/{room_id}/decision/{decision_id}"
         )
-        return body.get("data", {})
+        return single_record(body)
 
     def get_agent_runs(
         self,
@@ -639,6 +848,8 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             "ratings_continuous": self.get_ratings(participant_id, kind="continuous", **common),
             "ratings_sparse": self.get_ratings(participant_id, kind="sparse", **common),
             "components": self.get_components(participant_id, **common),
+            "eyetracking": self.get_eyetracking(participant_id, **common),
+            "voice": self.get_voice(participant_id, **common),
             "questionnaire": self.get_questionnaire(participant_id, **common),
             "instructions": self.get_instructions(participant_id, **common),
             "consent": self.get_consent(participant_id, **common),
@@ -661,7 +872,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         download_path = recording.get("downloadPath")
         if download_path:
             body = self._transport.get(download_path)
-            return (body.get("data") or {}).get("url")
+            return single_record(body).get("url")
         return get_download_url(recording)
 
     def download_recording(

hyperstudy/experiments.py

@@ -5,10 +5,9 @@ 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 ._http import HttpTransport, single_record
 from ._pagination import fetch_all_pages
 from .models import camelize_wire
 
@@ -43,9 +42,7 @@ def _build_experiment_payload(
         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)
+    payload.update(camelize_wire(overrides))
     return payload
 
 
@@ -105,15 +102,23 @@ class ExperimentMixin:
             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
+        record = single_record(body)
         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
+        return single_record(body)
+
+    def export_experiment(self, experiment_id: str) -> dict[str, Any]:
+        """Export an experiment as portable JSON.
+
+        Returns:
+            The export payload (experiment definition plus media-asset
+            manifest), suitable for re-import.
+        """
+        body = self._transport.get(f"experiments/{experiment_id}/export")
+        return single_record(body)
 
     # ------------------------------------------------------------------
     # Write
@@ -160,8 +165,7 @@ class ExperimentMixin:
                 "(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
+        record = single_record(body)
         return ExperimentInfo(record)
 
     def update_experiment(
@@ -173,6 +177,11 @@ class ExperimentMixin:
     ) -> dict[str, Any]:
         """Update an experiment.
 
+        Each top-level field you pass replaces the stored one whole: passing
+        ``agent_config=AgentConfig(voice_turn_taking=...)`` also clears any
+        stored ``role_overrides``, so send the complete ``agent_config``.
+        Only the owner or an organization admin may change ``visibility``.
+
         Args:
             experiment_id: ID of the experiment to update.
             experiment: Optional typed :class:`Experiment` carrying the new
@@ -190,8 +199,7 @@ class ExperimentMixin:
                 "(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
+        return single_record(body)
 
     def validate_experiment(
         self,
@@ -210,8 +218,7 @@ class ExperimentMixin:
             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
+        return single_record(body)
 
     def delete_experiment(
         self, experiment_id: str, *, skip_data_check: bool = False

hyperstudy/models.py

@@ -29,20 +29,56 @@ _FREEFORM_MAP_FIELDS = frozenset({
     "roleOverrides",
 })
 
+# Fields whose whole value goes on the wire exactly as written, as
+# (parent field, field) pairs; a parent of None is the top level of an
+# experiment or persona payload. Their keys belong to someone else: a
+# provider's raw request params (extraParams), the voice engine's
+# turn-detection settings, which use OpenAI's snake_case names
+# (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.
+_VERBATIM_FIELDS = frozenset({
+    (None, "extraParams"), (None, "cognition"), (None, "stimulusMappings"),
+    (None, "metadata"), (None, "prolific_config"),
+    ("voiceTurnTaking", "engineTurnDetection"),
+})
+
+# Experiment fields the backend stores under snake_case names.
+_SNAKE_CASE_FIELDS = frozenset({"prolific_enabled", "prolific_config"})
+
+
+def _wire_key(key: str) -> str:
+    return key if key in _SNAKE_CASE_FIELDS else to_camel(key)
+
+
+def _dump(model: BaseModel) -> dict[str, Any]:
+    return model.model_dump(by_alias=True, exclude_none=True)
+
 
 def camelize_wire(value: Any, _parent_key: "str | None" = None) -> Any:
     """Recursively convert snake_case dict keys to camelCase for the wire format.
 
     Skips converting the immediate keys of free-form map fields (variables, roles,
     globalComponents, globalComponentsVisibility) — those are user-defined names —
-    but still recurses into their values.
+    but still recurses into their values. Values of ``_VERBATIM_FIELDS`` are
+    passed through untouched; their positions are relative to the payload root,
+    so call this on a whole experiment or persona payload, not a sub-dict.
+
+    A typed model is dumped in its own wire format, the same one the typed
+    builders send: its declared fields are aliased and its dict-valued fields
+    are sent as written.
     """
+    if isinstance(value, BaseModel):
+        return _dump(value)
     if isinstance(value, dict):
         skip_keys = _parent_key in _FREEFORM_MAP_FIELDS
         out: dict[str, Any] = {}
         for k, v in value.items():
-            new_key = k if skip_keys else (to_camel(k) if isinstance(k, str) else k)
-            out[new_key] = camelize_wire(v, _parent_key=new_key)
+            new_key = k if skip_keys else (_wire_key(k) if isinstance(k, str) else k)
+            if (_parent_key, new_key) in _VERBATIM_FIELDS:
+                out[new_key] = _dump(v) if isinstance(v, BaseModel) else v
+            else:
+                out[new_key] = camelize_wire(v, _parent_key=new_key)
         return out
     if isinstance(value, list):
         return [camelize_wire(v, _parent_key=_parent_key) for v in value]
@@ -159,17 +195,62 @@ class PromptLayer(_Model):
     additional_instructions: Optional[str] = None
 
 
+class EngineTurnDetection(BaseModel):
+    """Turn detection handed to the voice engine.
+
+    The keys are the engine's own (OpenAI realtime) names, so unlike every
+    other model here this one is sent in snake_case, exactly as written.
+    ``server_vad`` takes ``threshold``, ``prefix_padding_ms`` and
+    ``silence_duration_ms``; ``semantic_vad`` takes ``eagerness``.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str  # "server_vad" | "semantic_vad"
+    threshold: Optional[float] = Field(default=None, ge=0, le=1)
+    prefix_padding_ms: Optional[int] = Field(default=None, ge=0, le=2000)
+    silence_duration_ms: Optional[int] = Field(default=None, ge=100, le=5000)
+    eagerness: Optional[str] = None  # semantic_vad: low | medium | high | auto
+
+
+class VoiceTurnTaking(_Model):
+    """How an experiment's voice agents take turns.
+
+    Unset, the engine detects turns with ``server_vad`` and 500 ms of
+    silence, and a spoken reply is cut off after 60 s.
+    """
+
+    mode: Optional[str] = None  # "engine" (the only mode so far)
+    engine_turn_detection: Optional[EngineTurnDetection] = None
+    min_response_delay_ms: Optional[int] = Field(default=None, ge=0, le=10_000)
+    max_response_ms: Optional[int] = Field(default=None, ge=1000, le=300_000)
+
+
+class VoiceTranscription(_Model):
+    """Transcription of participants' speech by the voice engine (off unless enabled).
+
+    ``language`` is a two-letter ISO-639-1 hint for a study run in one
+    language; unset, the model detects it.
+    """
+
+    enabled: Optional[bool] = None
+    model: Optional[str] = None  # gpt-4o-transcribe (default) | gpt-4o-mini-transcribe | whisper-1
+    language: Optional[str] = Field(default=None, pattern=r"^[a-z]{2}$")
+
+
 class AgentConfig(_Model):
     """Experiment-level agent inputs.
 
-    The bound persona is the source of truth for provider/model/prompt;
-    the experiment contributes only per-role prompt overrides, pacing,
-    and the random seed.
+    The bound persona is the source of truth for provider/model/prompt and
+    voice; the experiment contributes per-role prompt overrides, pacing, the
+    random seed, and how its voice agents take turns and transcribe speech.
     """
 
     role_overrides: Optional[dict[str, PromptLayer]] = None
-    pacing: Optional[dict[str, Any]] = None
+    pacing: Optional[dict[str, Any]] = None  # sent as written: {"readingOffsetMs": 300, ...}
     seed: Optional[int] = None
+    voice_turn_taking: Optional[VoiceTurnTaking] = None
+    voice_transcription: Optional[VoiceTranscription] = None
 
 
 class Guardrails(_Model):
@@ -182,15 +263,50 @@ class Guardrails(_Model):
     max_consecutive_decision_errors: Optional[int] = Field(default=None, ge=1)
 
 
+class RealtimeVoice(_Model):
+    """The realtime speech engine behind a voice persona."""
+
+    provider: str  # "openai" (the only provider so far)
+    model: Optional[str] = None  # e.g. "gpt-realtime-2.1"; the provider's default when unset
+
+
+class PersonaVoice(_Model):
+    """Gives a persona a voice in the experiment's audio.
+
+    Only ``engine="realtime"`` with ``realtime=RealtimeVoice(provider="openai")``
+    is supported so far. ``preset`` is the provider's voice (OpenAI: alloy,
+    ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar); ``style``
+    is natural-language delivery direction, e.g. ``"warm, a little hesitant"``.
+    """
+
+    engine: str  # "realtime"
+    preset: Optional[str] = None
+    speed: Optional[float] = Field(default=None, ge=0.25, le=1.5)
+    style: Optional[str] = Field(default=None, max_length=500)
+    realtime: Optional[RealtimeVoice] = None
+
+
+class PersonaChat(_Model):
+    """Whether the agent opens a text chat, and how long it waits first."""
+
+    initiate: Optional[bool] = None
+    initiate_delay_ms: Optional[int] = Field(default=None, gt=0)
+
+
 class Persona(_Model):
     """A reusable AI-agent definition (agent library entry).
 
-    The persona owns the agent's identity, model settings, guardrails and
-    (optionally) cognition. ``cognition`` / ``offline_cognition`` are accepted
-    as plain dicts — their schema is experimental and still evolving.
+    The persona owns the agent's identity, model settings, guardrails,
+    voice and (optionally) cognition. ``cognition`` is accepted as a plain
+    dict — its schema is experimental and still evolving. Offline loops live
+    inside ``cognition["config"]["contexts"][<name>]["offline"]``.
+
+    ``display_name`` is the name other participants see in chat and video;
+    empty, they see ``name``.
     """
 
     name: str = Field(min_length=1)
+    display_name: Optional[str] = None
     description: Optional[str] = None
     prompt: Optional[PromptLayer] = None
     provider: Optional[str] = None  # anthropic (default) | openai | gemini | custom
@@ -204,13 +320,13 @@ class Persona(_Model):
     disable_thinking: Optional[bool] = None
     seed: Optional[int] = None
     cognition: Optional[dict[str, Any]] = None
-    offline_cognition: Optional[dict[str, Any]] = None
     memory_persistence: Optional[str] = None  # "none" (default) | "cross-experiment"
-    language: Optional[str] = None
     seed_memories: Optional[list[dict[str, Any]]] = None
     guardrails: Optional[Guardrails] = None
-    pacing: Optional[dict[str, Any]] = None
-    visibility: Optional[str] = None  # create-time only: private | organization | public
+    pacing: Optional[dict[str, Any]] = None  # sent as written: {"readingOffsetMs": 300, ...}
+    chat: Optional[PersonaChat] = None
+    voice: Optional[PersonaVoice] = None
+    visibility: Optional[str] = None  # private (default) | organization | public
 
 
 class WaitingRoomConfig(_Model):
@@ -224,6 +340,16 @@ class DisconnectTimeout(_Model):
     auto_reconnect_delay: Optional[int] = Field(default=None, ge=0)
 
 
+class ExperimenterMessageStyle(_Model):
+    """Text style of messages the experimenter sends from deployment monitoring.
+
+    Unset, messages are 20px white.
+    """
+
+    font_size: Optional[float] = Field(default=None, ge=10, le=72)
+    color: Optional[str] = Field(default=None, pattern=r"^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
 class InstructionsPage(_Model):
     title: Optional[str] = None
     content: Optional[str] = None
@@ -263,6 +389,16 @@ class Experiment(_Model):
     instructions_content: Optional[str] = None
     instructions_pages: Optional[list[InstructionsPage]] = None
     post_experiment_questionnaire: Optional[PostExperimentQuestionnaire] = None
+    # Only the owner or an organization admin may change visibility.
+    visibility: Optional[str] = None  # private (default) | organization | public
+    tags: Optional[list[str]] = None
+    enable_participant_messaging: Optional[bool] = None
+    experimenter_message_style: Optional[ExperimenterMessageStyle] = None
+    stimulus_mappings: Optional[dict[str, Any]] = None
+    device_integration: Optional[dict[str, Any]] = None
+    # Stored under snake_case names by the backend.
+    prolific_enabled: Optional[bool] = Field(default=None, alias="prolific_enabled")
+    prolific_config: Optional[dict[str, Any]] = Field(default=None, alias="prolific_config")
 
 
 # ---------------------------------------------------------------------------
@@ -280,11 +416,16 @@ class Experiment(_Model):
 # of ``output_variable=``) gets the factory's value, not their typo.
 
 
+def _config_extra(extra: dict[str, Any]) -> dict[str, Any]:
+    """A factory's extra kwargs, converted as fields of a component ``config``."""
+    return camelize_wire(extra, _parent_key="config")
+
+
 def show_text(text: str, *, id: Optional[str] = None, **extra: Any) -> FocusComponent:
     """Build a ``showtext`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_TEXT,
-        config={**camelize_wire(extra), "text": text},
+        config={**_config_extra(extra), "text": text},
         id=id,
     )
 
@@ -293,7 +434,7 @@ def show_image(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComp
     """Build a ``showimage`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_IMAGE,
-        config={**camelize_wire(extra), "url": url},
+        config={**_config_extra(extra), "url": url},
         id=id,
     )
 
@@ -302,7 +443,7 @@ def show_video(url: str, *, id: Optional[str] = None, **extra: Any) -> FocusComp
     """Build a ``showvideo`` focus component."""
     return FocusComponent(
         type=ComponentType.SHOW_VIDEO,
-        config={**camelize_wire(extra), "url": url},
+        config={**_config_extra(extra), "url": url},
         id=id,
     )
 
@@ -317,7 +458,7 @@ def vas_rating(
     """Build a ``vasrating`` (visual analog scale) focus component."""
     return FocusComponent(
         type=ComponentType.VAS_RATING,
-        config={**camelize_wire(extra), "prompt": prompt, "outputVariable": output_variable},
+        config={**_config_extra(extra), "prompt": prompt, "outputVariable": output_variable},
         id=id,
     )
 
@@ -332,7 +473,7 @@ def text_input(
     """Build a ``textinput`` focus component."""
     return FocusComponent(
         type=ComponentType.TEXT_INPUT,
-        config={**camelize_wire(extra), "prompt": prompt, "outputVariable": output_variable},
+        config={**_config_extra(extra), "prompt": prompt, "outputVariable": output_variable},
         id=id,
     )
 
@@ -349,7 +490,7 @@ def multiple_choice(
     return FocusComponent(
         type=ComponentType.MULTIPLE_CHOICE,
         config={
-            **camelize_wire(extra),
+            **_config_extra(extra),
             "prompt": prompt,
             "options": list(options),
             "outputVariable": output_variable,
@@ -362,7 +503,7 @@ def waiting(duration_ms: int, *, id: Optional[str] = None, **extra: Any) -> Focu
     """Build a ``waiting`` focus component."""
     return FocusComponent(
         type=ComponentType.WAITING,
-        config={**camelize_wire(extra), "durationMs": int(duration_ms)},
+        config={**_config_extra(extra), "durationMs": int(duration_ms)},
         id=id,
     )
 
@@ -379,7 +520,7 @@ def likert_scale(
     return FocusComponent(
         type=ComponentType.LIKERT_SCALE,
         config={
-            **camelize_wire(extra),
+            **_config_extra(extra),
             "prompt": prompt,
             "outputVariable": output_variable,
             "scalePoints": int(scale_points),
@@ -400,7 +541,7 @@ def ranking(
     return FocusComponent(
         type=ComponentType.RANKING,
         config={
-            **camelize_wire(extra),
+            **_config_extra(extra),
             "prompt": prompt,
             "options": list(options),
             "outputVariable": output_variable,
@@ -425,6 +566,18 @@ __all__ = [
     "DisconnectTimeout",
     "InstructionsPage",
     "PostExperimentQuestionnaire",
+    "ExperimenterMessageStyle",
+    # Agent models
+    "AgentConfig",
+    "PromptLayer",
+    "VoiceTurnTaking",
+    "EngineTurnDetection",
+    "VoiceTranscription",
+    "Persona",
+    "PersonaVoice",
+    "RealtimeVoice",
+    "PersonaChat",
+    "Guardrails",
     # Factories
     "show_text",
     "show_image",

hyperstudy/personas.py

@@ -7,8 +7,11 @@ Personas are reusable AI-agent definitions. These methods target the
 
 from __future__ import annotations
 
+import warnings
 from typing import TYPE_CHECKING, Any
 
+from ._http import single_record
+
 if TYPE_CHECKING:
     from .models import Persona
 
@@ -25,6 +28,22 @@ def _persona_payload(persona: "Persona | None", kwargs: dict[str, Any]) -> dict[
         payload.update(persona.model_dump(by_alias=True, exclude_none=True))
     if kwargs:
         payload.update(camelize_wire(kwargs))
+    # The server hard-discards offlineCognition (offline loops now live inside
+    # cognition.config.contexts.<name>.offline), so never send it — including
+    # when a Persona was rebuilt from an older API response via extra fields.
+    payload.pop("offlineCognition", None)
+    payload.pop("offline_cognition", None)
+    # Personas no longer have a language: nothing read it, and the server
+    # discards it. Older stored personas still carry the key, so strip it. It
+    # was stored as null unless someone set it, so a value means someone
+    # believed it did something: tell them, wherever it came from.
+    if payload.pop("language", None):
+        warnings.warn(
+            "Persona 'language' was removed and is ignored by the server. To set "
+            "the language participants speak, use the experiment's "
+            "agent_config.voice_transcription.language.",
+            stacklevel=3,
+        )
     return payload
 
 
@@ -43,7 +62,7 @@ class PersonaMixin:
     def get_persona(self, persona_id: str) -> dict[str, Any]:
         """Get one persona by ID."""
         body = self._transport.get(f"personas/{persona_id}")
-        return body.get("data", {})
+        return single_record(body)
 
     def create_persona(
         self,
@@ -69,7 +88,7 @@ class PersonaMixin:
         if not payload.get("name"):
             raise ValueError("Persona name is required")
         body = self._transport.post("personas", json=payload)
-        return body.get("data", {})
+        return single_record(body)
 
     def update_persona(
         self,
@@ -80,14 +99,22 @@ class PersonaMixin:
     ) -> dict[str, Any]:
         """Update a persona (merge-patch).
 
-        Only the fields you pass are changed; everything else on the stored
-        persona is preserved.
+        Only the top-level fields you pass are changed; everything else on
+        the stored persona is preserved. A nested block you pass (``voice``,
+        ``chat``, ``prompt``, ``guardrails``, ``cognition``) replaces the
+        stored block whole, so send all of it. For a persona that has a
+        voice (``voice`` is ``None`` on a text-only persona)::
+
+            voice = hs.get_persona(pid)["voice"]
+            hs.update_persona(pid, voice={**voice, "speed": 1.1})
+
+        Only the owner or an organization admin may change ``visibility``.
         """
         payload = _persona_payload(persona, kwargs)
         if not payload:
             raise ValueError("No fields to update")
         body = self._transport.put(f"personas/{persona_id}", json=payload)
-        return body.get("data", {})
+        return single_record(body)
 
     def delete_persona(self, persona_id: str) -> None:
         """Delete a persona."""
@@ -100,4 +127,16 @@ class PersonaMixin:
             The new persona (named ``"<original name> (copy)"``).
         """
         body = self._transport.post(f"personas/{persona_id}/duplicate")
-        return body.get("data", {})
+        return single_record(body)
+
+    def get_cognition_catalog(self) -> dict[str, Any]:
+        """Fetch the cognition authoring catalog.
+
+        Lists the valid building blocks for persona ``cognition`` configs.
+        Requires the ``read:personas`` scope.
+
+        Returns:
+            Dict with ``abilities``, ``recipes``, and ``offlineRecipes``.
+        """
+        body = self._transport.get("agent-cognition/catalog")
+        return single_record(body)

{hyperstudy-0.4.0.dist-info → hyperstudy-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hyperstudy
-Version: 0.4.0
+Version: 0.4.2
 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
@@ -75,9 +75,11 @@ All data retrieval methods follow the same pattern:
 events        = hs.get_events("exp_id")
 recordings    = hs.get_recordings("exp_id")
 chat          = hs.get_chat("exp_id")
+voice         = hs.get_voice("exp_id")   # voice agent conversations
 videochat     = hs.get_videochat("exp_id")
 sync          = hs.get_sync("exp_id")
 ratings       = hs.get_ratings("exp_id", kind="continuous")
+eyetracking   = hs.get_eyetracking("exp_id")
 components    = hs.get_components("exp_id")
 participants  = hs.get_participants("exp_id")
 rooms         = hs.get_rooms("exp_id")
@@ -86,6 +88,16 @@ rooms         = hs.get_rooms("exp_id")
 questionnaire = hs.get_questionnaire("exp_id")
 instructions  = hs.get_instructions("exp_id")
 consent       = hs.get_consent("exp_id")
+
+# Room-scoped: reconstructed shared-variable timeline
+# -> {"writes", "timeline", "variable_names", "dropped_writes"}
+variables = hs.get_variables("room_id")
+
+# Per-data-type document counts for one participant in a room
+counts = hs.get_counts("participant_id", room_id="room_id")
+
+# Whether you may view / export an experiment's data (no data fetched)
+access = hs.check_data_access("exp_id")  # {"canView": True, "canExport": False}
 ```
 
 ### Output Formats
@@ -107,6 +119,9 @@ events = hs.get_events(
     sort="onset",
     limit=100,
 )
+
+ratings = hs.get_components("exp_id", component_type="vasrating", completed=True)
+abandoned = hs.get_participants("exp_id", completion_code="ABANDONED")
 ```
 
 ### Auto-Pagination
@@ -130,6 +145,9 @@ exp = hs.get_experiment("exp_id")
 new_exp = hs.create_experiment(name="My Study", description="...")
 hs.update_experiment("exp_id", name="Updated Name")
 hs.delete_experiment("exp_id")
+
+# Portable experiment JSON (definition + media-asset manifest)
+export = hs.export_experiment("exp_id")
 ```
 
 ### Building experiments programmatically (0.3.0+)
@@ -215,8 +233,54 @@ hs.run_more(dep["id"], rooms=5, budget_usd=2.5) # additive batch
 decisions = hs.get_agent_decisions(exp["id"])                    # per-turn logs
 runs = hs.get_agent_runs(exp["id"])                              # run manifests
 detail = hs.get_agent_decision("room_id", "participantId_3")     # full blobs
+
+# --- Cognition authoring catalog ---
+catalog = hs.get_cognition_catalog()  # {"abilities": ..., "recipes": ..., "offlineRecipes": ...}
 ```
 
+### Voice agents
+
+A persona with a `voice` speaks in the experiment's audio. The experiment sets how its voice agents take turns and whether participants' speech is transcribed.
+
+```python
+from hyperstudy import (
+    PersonaVoice, RealtimeVoice, VoiceTurnTaking, EngineTurnDetection, VoiceTranscription,
+)
+
+voice_persona = hs.create_persona(persona=Persona(
+    name="Interviewer",
+    display_name="Sam",                      # what other participants see
+    provider="openai",
+    voice=PersonaVoice(
+        engine="realtime",
+        preset="marin",                      # the provider's voice
+        speed=1.0,
+        style="warm, a little hesitant",
+        realtime=RealtimeVoice(provider="openai", model="gpt-realtime-2.1"),
+    ),
+))
+
+exp = hs.create_experiment(experiment=Experiment(
+    name="Voice interview",
+    runtime="v2",
+    roles={"interviewer": Role(mode="agent", persona_id=voice_persona["id"])},
+    agent_config=AgentConfig(
+        voice_turn_taking=VoiceTurnTaking(
+            engine_turn_detection=EngineTurnDetection(type="server_vad", silence_duration_ms=800),
+            min_response_delay_ms=250,
+        ),
+        voice_transcription=VoiceTranscription(enabled=True, language="en"),
+    ),
+    states=[...],
+))
+
+# One room's conversation: every speaker's turns, plus what the engine was told
+conversation = hs.get_voice("room_id", scope="room")
+turns = conversation[conversation["kind"] == "utterance"][["onset", "speaker", "transcript"]]
+```
+
+`update_persona` and `update_experiment` replace a nested block whole, so pass the complete `voice` or `agent_config` when changing one setting in it.
+
 Persona methods need the `read:personas` / `write:personas` API-key scopes; deployment launch/control needs `write:deployments`; agent data reads need `read:events`.
 
 ## All Data for a Participant
@@ -224,8 +288,8 @@ Persona methods need the `read:personas` / `write:personas` API-key scopes; depl
 ```python
 data = hs.get_all_data("participant_id", room_id="room_id")
 # Returns dict with keys: events, recordings, chat, videochat, sync,
-# ratings_continuous, ratings_sparse, components, questionnaire,
-# instructions, consent, agent_decisions
+# ratings_continuous, ratings_sparse, components, eyetracking, voice,
+# questionnaire, instructions, consent, agent_decisions
 ```
 
 ## API Key

hyperstudy-0.4.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+hyperstudy/__init__.py,sha256=8yoNbRsLUNtzRWR98EHvrb78hcr4YeN7DoTy7rnnsA0,2369
+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
+hyperstudy/_http.py,sha256=QG9JA_2Pug620PKlQRqo_PZ9ycMWjG4FD_EOGclLUJ8,5196
+hyperstudy/_pagination.py,sha256=2NbvNGW_jFQkYquSTi3SNkAmGgsbKop7J9LkGaZWwWA,1812
+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/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.0.dist-info → hyperstudy-0.4.2.dist-info}/WHEEL

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

hyperstudy-0.4.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-hyperstudy/__init__.py,sha256=ZbHxlP2hnepEMK29ebttkRY_uJC1YuMTPcbMt_ov7cs,2047
-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
-hyperstudy/_http.py,sha256=_RS0ZaRAcKvFQ2NF9II7PpcojE-lTYT6CslaJNlgfPQ,4569
-hyperstudy/_pagination.py,sha256=2NbvNGW_jFQkYquSTi3SNkAmGgsbKop7J9LkGaZWwWA,1812
-hyperstudy/_types.py,sha256=Mw5KJFMXgLi17U6F08UR8BRfhAYrsj95Y1byhHCJTDU,682
-hyperstudy/client.py,sha256=5WJGP3ggWIHq-NII_ikKydpj2RVVf56KRc2MEklb3I4,31897
-hyperstudy/exceptions.py,sha256=z_1Ngiq-RU-1yyDI_JqvQ5CvYm2jQ_lyJ9TUbqUKKv8,1529
-hyperstudy/experiments.py,sha256=ZGCbOEwmzXq-HVJ-f7iPsinYZDxq1RXUZ7mBqo2T3hU,8472
-hyperstudy/models.py,sha256=1wA_USRzqKSY5pEQkK89wj0dDhkMeBFanzyRsIL_pvU,13820
-hyperstudy/personas.py,sha256=LukXLMiz7N3t06m1t7RZWQLrQRMMU1KsfGkwE7BhOBM,3485
-hyperstudy-0.4.0.dist-info/METADATA,sha256=FOwcQWXh2iwAnvcIjohWyZ6EiitqqNucEvcS8O-nd40,7900
-hyperstudy-0.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-hyperstudy-0.4.0.dist-info/licenses/LICENSE,sha256=WJdwRhBIOiiQ6lyK4l95u5IJYuuT-XxzwYRraS31NME,1067
-hyperstudy-0.4.0.dist-info/RECORD,,