hyperstudy 0.4.0__tar.gz → 0.4.2__tar.gz

{hyperstudy-0.4.0 → 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.0 → 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.0 → hyperstudy-0.4.2}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # 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
+
+- **Removed `Persona.offline_cognition`.** The server now hard-discards this field (`offlineCognition` is always null server-side); offline loops live inside `cognition.config.contexts.<name>.offline`. The SDK also strips `offlineCognition` from create/update payloads so personas rebuilt from older API responses never send it.
+
+### Features
+
+- **Eye-tracking data access**: `get_eyetracking(scope_id, scope="experiment"|"room"|"participant", room_id=)` with the standard pagination/output options, plus `DataType.EYETRACKING`. `get_all_data` now includes an `eyetracking` key.
+- **Room variables**: `get_variables(room_id)` — the reconstructed shared-variable timeline for a room. Returns `{writes, timeline, variable_names, dropped_writes}`: the write log (each write tagged with source and persisted flag), the per-state forward-filled snapshot matrix, the ordered variable set, and any writes that failed the server's ground-truth cross-checks (a bug signal).
+- **Participant counts**: `get_counts(participant_id, room_id=)` — cheap per-data-type document counts (`counts` / `hasData`) for a participant in a room.
+- **Experiment export**: `export_experiment(experiment_id)` — portable experiment JSON (definition plus media-asset manifest), suitable for re-import.
+- **Cognition catalog**: `get_cognition_catalog()` — the valid building blocks for persona `cognition` configs (`abilities`, `recipes`, `offlineRecipes`). Requires the `read:personas` scope.
+
 ## v0.4.0
 
 ### Features

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

@@ -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.0 → hyperstudy-0.4.2}/README.md

@@ -40,9 +40,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")
@@ -51,6 +53,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
@@ -72,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
@@ -95,6 +110,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+)
@@ -180,8 +198,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
@@ -189,8 +253,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.0 → hyperstudy-0.4.2}/pyproject.toml

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

{hyperstudy-0.4.0 → 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.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-0.4.0 → 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.0 → hyperstudy-0.4.2}/src/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"