hyperstudy 0.4.1__tar.gz → 0.4.2__tar.gz

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/.github/workflows/publish.yml

@@ -6,7 +6,8 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # Python 3.9 has no build for ubuntu-latest (26.04); pinned until 3.9 support is dropped.
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/.github/workflows/test.yml

@@ -7,7 +7,8 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    # Python 3.9 has no build for ubuntu-latest (26.04); pinned until 3.9 support is dropped.
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.4.2
+
+### Breaking Changes
+
+- **Removed `Persona.language`.** The server discarded it and nothing read it. The SDK strips it from persona payloads, so personas rebuilt from older stored documents still save, and warns when it drops a value someone set. To set the language participants speak, use the experiment's `agent_config.voice_transcription.language`.
+
+### Fixes
+
+- **Single-object responses are now returned as objects.** The v3 API always sends `data` as an array, so `get_persona`, `create_persona`, `update_persona`, `duplicate_persona`, `create_deployment`, `get_agent_spend`, `run_more`, `retry_room` and `get_agent_decision` returned a one-element list instead of a dict, and `download_recording` / `download_recordings` raised `AttributeError` for recordings with a `downloadPath`. A single-object response with no record now raises `HyperStudyError` instead of returning `{}`. Test mocks now build the envelope exactly as the server does.
+- **Keys that are not the SDK's own are sent as written** on the kwargs and raw-dict paths. Previously `extra_params={"top_k": 20}` reached a custom provider as `topK`, a cognition context named `post_trial` was stored as `postTrial`, voice turn-detection settings (`silence_duration_ms`, ...) were camelCased and rejected by the server, `prolific_enabled` / `prolific_config` were renamed and dropped, and stimulus mapping names were renamed. Schema fields such as `waiting_room_config` are still converted.
+- **Typed models can be passed as keyword arguments**: `update_experiment(agent_config=AgentConfig(...))`, `update_experiment(waiting_room_config=WaitingRoomConfig(...))` and `update_persona(voice=PersonaVoice(...))` raised `TypeError: Object of type ... is not JSON serializable`.
+- `Persona(display_name=...)` and other undeclared persona fields were sent in snake_case and silently ignored by the server; `display_name` is now a declared field.
+
+### Features
+
+- **Voice agent conversations**: `get_voice(scope_id, scope=, deployment_id=, room_id=, include_context=, order=)` returns one row per voice event: every speaker's utterances with transcripts, discarded and silent agent replies, what the voice engine was told, and engine connection drops. `DataType.VOICE`; `get_all_data` includes `voice`. Requires the `read:events` scope.
+- **Voice personas**: `Persona.voice` (`PersonaVoice`, `RealtimeVoice`: engine, preset, speed, style, realtime provider and model), `Persona.display_name`, and `Persona.chat` (`PersonaChat`: `initiate`, `initiate_delay_ms`).
+- **Voice settings per experiment**: `AgentConfig.voice_turn_taking` (`VoiceTurnTaking` with `EngineTurnDetection`, sent in the engine's own snake_case) and `AgentConfig.voice_transcription` (`VoiceTranscription`). Ranges mirror the server's validators, so mistakes fail when the model is built.
+- **Experiment fields**: `visibility`, `tags`, `enable_participant_messaging`, `experimenter_message_style` (`ExperimenterMessageStyle`), `stimulus_mappings`, `device_integration`, `prolific_enabled`, `prolific_config`.
+- **Data filters**: `get_components(component_type=, state_id=, completed=, start_time=, end_time=, sort=, order=)`, `get_participants(completion_code=, sort=, order=)`, `get_rooms(sort=, order=)`.
+- **`check_data_access(experiment_id)`**: `{canView, canExport}` without fetching data.
+
+### Notes
+
+- `update_persona` and `update_experiment` replace a nested block (`voice`, `chat`, `prompt`, `guardrails`, `agent_config`, ...) whole; pass the complete block to change one setting in it. Only an experiment's or persona's owner, or an organization admin, may change its `visibility`.
+- New server-side columns arrive in the existing DataFrames with no SDK change: event clock fields (`clientTime`, `timestampSource`, `clockOffsetMs`, `rawOnset`, `clockOffsetApplied`), `decisionError` on agent decisions, and `completionReason` / `agentStartFailures` on rooms.
+
 ## v0.4.1
 
 ### Breaking Changes

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hyperstudy
-Version: 0.4.1
+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,6 +75,7 @@ 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")
@@ -94,6 +95,9 @@ 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
@@ -115,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
@@ -231,6 +238,49 @@ detail = hs.get_agent_decision("room_id", "participantId_3")     # full blobs
 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
@@ -238,7 +288,7 @@ 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, eyetracking,
+# ratings_continuous, ratings_sparse, components, eyetracking, voice,
 # questionnaire, instructions, consent, agent_decisions
 ```
 

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/README.md

@@ -40,6 +40,7 @@ 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")
@@ -59,6 +60,9 @@ 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
@@ -80,6 +84,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
@@ -196,6 +203,49 @@ detail = hs.get_agent_decision("room_id", "participantId_3")     # full blobs
 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
@@ -203,7 +253,7 @@ 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, eyetracking,
+# ratings_continuous, ratings_sparse, components, eyetracking, voice,
 # questionnaire, instructions, consent, agent_decisions
 ```
 

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hyperstudy"
-version = "0.4.1"
+version = "0.4.2"
 description = "Python SDK for the HyperStudy experiment platform API"
 readme = "README.md"
 license = "MIT"

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/src/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.1"
+__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-0.4.1 → hyperstudy-0.4.2}/src/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-0.4.1 → hyperstudy-0.4.2}/src/hyperstudy/_types.py

@@ -17,6 +17,7 @@ class DataType(str, Enum):
     EVENTS = "events"
     RECORDINGS = "recordings"
     CHAT = "chat"
+    VOICE = "voice"
     VIDEOCHAT = "videochat"
     SYNC = "sync"
     RATINGS = "ratings"

{hyperstudy-0.4.1 → hyperstudy-0.4.2}/src/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,
@@ -271,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(
@@ -291,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(
@@ -310,15 +412,23 @@ 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,
         )
@@ -381,8 +491,18 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
         body = self._transport.get(
             f"data/counts/participant/{participant_id}", params={"roomId": room_id}
         )
-        data = body.get("data", [])
-        return data[0] if isinstance(data, list) and data else data
+        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
@@ -513,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,
@@ -573,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
@@ -598,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."""
@@ -609,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
@@ -681,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,
@@ -730,6 +849,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             "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),
@@ -752,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(