hyperstudy 0.4.1__tar.gz → 0.4.3__tar.gz

{hyperstudy-0.4.1 → hyperstudy-0.4.3}/.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.3}/.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.3}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## v0.4.3
+
+### Features
+
+- **State randomization (V2 runner)**: `Experiment.clusters` (`Cluster`, `ClusterRule`: `type` `shuffle` | `keep`, `across_groups` `independent` | `same`). States and groups join a cluster with `cluster_id`. Each room draws its order once, so everyone in the room runs the same order. Clusters are used only while `randomize_states=True`, the same setting the legacy runner uses to shuffle each participant's order; with it `False` they are kept but not used.
+- **Variable definitions (V2 runner)**: `Experiment.variable_definitions` (`VariableDefinition` with `kind` `constant`, `random` or `computed`; `Distribution` for random variables: `uniform`, `normal`, `exponential` or `list`, drawn `per_use` or `per_room`). A TIMED state draws its duration from a random variable with `TransitionRules(type="TIMED", variable_id=...)`. Ids are generated when omitted.
+- **`Group`** model for `Experiment.groups` (`id`, `name`, `order`, `children`, `cluster_id`).
+- A constant's `value` and a list distribution's `values` are sent exactly as written on the kwargs and raw-dict paths, like other researcher-named data.
+
+### Notes
+
+- Both fields need `runtime="v2"`, the server's default for new experiments. The server refuses non-empty `variable_definitions` on any other runtime, and refuses a create or update that would make clusters or variables invalid (`ValidationError`, reasons in `details["errors"]`).
+- Pass `runtime="v2"` to `validate_experiment` when validating variable definitions: servers older than v0.7.32 do not apply create's `"v2"` default in the dry run.
+
+## 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: hyperstudy
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -172,6 +179,38 @@ info = hs.create_experiment(experiment=exp)
 
 Component factories cover `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. For other component types, construct directly: `FocusComponent(type=ComponentType.X, config={...})`. See the [Experiment Authoring guide](https://docs.hyperstudy.io/experimenters/api-access/experiment-authoring) for the full reference.
 
+### Randomization and variables (V2 runner)
+
+Clusters randomize the order of states and groups once per room while `randomize_states=True`; with it `False` the clusters are kept but rooms run the listed order. Variable definitions hold constants, random draws and computed values. Both need `runtime="v2"` (the server's default for new experiments). On the legacy runner, `randomize_states=True` shuffles each participant's order instead.
+
+```python
+from hyperstudy import Cluster, ClusterRule, Distribution, TransitionRules, VariableDefinition
+
+iti = VariableDefinition(
+    name="iti_ms", kind="random",
+    distribution=Distribution(type="uniform", min=500, max=1500),
+)
+exp = Experiment(
+    name="Randomized study",
+    runtime="v2",
+    randomize_states=True,
+    clusters=[Cluster(id="block", rule=ClusterRule(type="shuffle"))],
+    variable_definitions=[
+        VariableDefinition(name="endowment", kind="constant", value=10),
+        VariableDefinition(name="doubled", kind="computed", expr="endowment * 2"),
+        iti,
+    ],
+    states=[
+        State(id="a", cluster_id="block", focus_component=show_text("You have {endowment}")),
+        State(id="b", cluster_id="block", focus_component=show_text("Doubled: {doubled}")),
+        State(id="pause", focus_component=show_text("+"),
+              transition_rules=TransitionRules(type="TIMED", variable_id=iti.id)),
+    ],
+)
+```
+
+The server refuses a create or update that would make clusters or variables invalid, raising `ValidationError` with the reasons in `err.details["errors"]`.
+
 ## Deployments
 
 ```python
@@ -231,6 +270,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 +320,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.3}/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
@@ -137,6 +144,38 @@ info = hs.create_experiment(experiment=exp)
 
 Component factories cover `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. For other component types, construct directly: `FocusComponent(type=ComponentType.X, config={...})`. See the [Experiment Authoring guide](https://docs.hyperstudy.io/experimenters/api-access/experiment-authoring) for the full reference.
 
+### Randomization and variables (V2 runner)
+
+Clusters randomize the order of states and groups once per room while `randomize_states=True`; with it `False` the clusters are kept but rooms run the listed order. Variable definitions hold constants, random draws and computed values. Both need `runtime="v2"` (the server's default for new experiments). On the legacy runner, `randomize_states=True` shuffles each participant's order instead.
+
+```python
+from hyperstudy import Cluster, ClusterRule, Distribution, TransitionRules, VariableDefinition
+
+iti = VariableDefinition(
+    name="iti_ms", kind="random",
+    distribution=Distribution(type="uniform", min=500, max=1500),
+)
+exp = Experiment(
+    name="Randomized study",
+    runtime="v2",
+    randomize_states=True,
+    clusters=[Cluster(id="block", rule=ClusterRule(type="shuffle"))],
+    variable_definitions=[
+        VariableDefinition(name="endowment", kind="constant", value=10),
+        VariableDefinition(name="doubled", kind="computed", expr="endowment * 2"),
+        iti,
+    ],
+    states=[
+        State(id="a", cluster_id="block", focus_component=show_text("You have {endowment}")),
+        State(id="b", cluster_id="block", focus_component=show_text("Doubled: {doubled}")),
+        State(id="pause", focus_component=show_text("+"),
+              transition_rules=TransitionRules(type="TIMED", variable_id=iti.id)),
+    ],
+)
+```
+
+The server refuses a create or update that would make clusters or variables invalid, raising `ValidationError` with the reasons in `err.details["errors"]`.
+
 ## Deployments
 
 ```python
@@ -196,6 +235,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 +285,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.3}/pyproject.toml

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

{hyperstudy-0.4.1 → hyperstudy-0.4.3}/src/hyperstudy/__init__.py

@@ -31,19 +31,31 @@ from .exceptions import (
 )
 from .models import (
     AgentConfig,
+    Cluster,
+    ClusterRule,
     ComponentType,
     DisconnectTimeout,
+    Distribution,
+    EngineTurnDetection,
     Experiment,
+    ExperimenterMessageStyle,
     FocusComponent,
     GlobalComponentType,
+    Group,
     Guardrails,
     InstructionsPage,
     Persona,
+    PersonaChat,
+    PersonaVoice,
     PostExperimentQuestionnaire,
     PromptLayer,
+    RealtimeVoice,
     Role,
     State,
     TransitionRules,
+    VariableDefinition,
+    VoiceTranscription,
+    VoiceTurnTaking,
     WaitingRoomConfig,
     likert_scale,
     multiple_choice,
@@ -56,7 +68,7 @@ from .models import (
     waiting,
 )
 
-__version__ = "0.4.1"
+__version__ = "0.4.3"
 
 __all__ = [
     "HyperStudy",
@@ -82,8 +94,20 @@ __all__ = [
     "AgentConfig",
     "PromptLayer",
     "Persona",
+    "PersonaVoice",
+    "RealtimeVoice",
+    "PersonaChat",
     "Guardrails",
+    "VoiceTurnTaking",
+    "EngineTurnDetection",
+    "VoiceTranscription",
+    "ExperimenterMessageStyle",
     "TransitionRules",
+    "Group",
+    "Cluster",
+    "ClusterRule",
+    "VariableDefinition",
+    "Distribution",
     "WaitingRoomConfig",
     "DisconnectTimeout",
     "InstructionsPage",

{hyperstudy-0.4.1 → hyperstudy-0.4.3}/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.3}/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"