hyperstudy 0.3.1__tar.gz → 0.5.0__tar.gz

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.5.0
+
+### 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
+
+- **Agent data access**: new methods for AI-agent experiment data —
+  `get_agent_decisions(scope_id, scope="experiment"|"room", detail=, limit=, participant_id=)` (per-turn decision logs plus run-manifest rows), `get_agent_decision(room_id, decision_id)` (single decision with full detail blobs: prompt, reasoning chain, peer-model snapshot, prediction update), and `get_agent_runs(experiment_id)` (run manifests with orphaned-run flags). Emits a warning when the server truncates decisions at the per-room limit.
+- `DataType.AGENT_DECISIONS` and `DataType.AGENT_RUNS` enum entries; `get_all_data` now includes an `agent_decisions` key (room-scope fetch filtered to the participant).
+- **Agent-role experiment authoring**: `Role` accepts `mode="agent"` and `persona_id`; new `AgentConfig` (per-role `role_overrides`, `pacing`, `seed`) and `PromptLayer` models; `Experiment` gains `runtime` and `agent_config` fields. Role-name keys in `role_overrides` are preserved (not camelized) on the wire.
+- **Persona management**: `list_personas`, `get_persona`, `create_persona`, `update_persona` (merge-patch), `delete_persona`, `duplicate_persona`, with typed `Persona` / `Guardrails` builders. Requires API-key scopes `read:personas` / `write:personas`.
+- **Agent deployment launch & control**: `create_deployment` (including agent-only deployments — rooms launch server-side immediately), `get_agent_spend`, `run_more`, `stop_room`, `retry_room`. Requires the `write:deployments` scope.
+
+### Fixes
+
+- `__version__` now matches the packaged version (was stuck at 0.3.0 while pyproject said 0.3.1).
+
 ## v0.3.1
 
 ### Features

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.3.1
+Version: 0.5.0
 Summary: Python SDK for the HyperStudy experiment platform API
 Project-URL: Homepage, https://hyperstudy.io
 Project-URL: Documentation, https://docs.hyperstudy.io/developers/python-sdk
@@ -78,6 +78,7 @@ chat          = hs.get_chat("exp_id")
 videochat     = hs.get_videochat("exp_id")
 sync          = hs.get_sync("exp_id")
 ratings       = hs.get_ratings("exp_id", kind="continuous")
+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 +87,13 @@ 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")
 ```
 
 ### Output Formats
@@ -130,6 +138,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+)
@@ -175,13 +186,60 @@ dep = hs.get_deployment("deployment_id")
 sessions = hs.get_deployment_sessions("deployment_id")
 ```
 
+## AI Agents
+
+Full agent workflow support: personas (the agent library), agent-role experiment authoring, agent-only deployment launch/control, and agent data.
+
+```python
+from hyperstudy import Persona, PromptLayer, Guardrails, Role, AgentConfig
+
+# --- Personas (agent library) ---
+persona = hs.create_persona(persona=Persona(
+    name="Curious Undergrad",
+    provider="anthropic",
+    model="claude-opus-4-8",
+    prompt=PromptLayer(persona="You are a curious undergraduate...",
+                       objective="Converse naturally with your partner."),
+    guardrails=Guardrails(max_turns=50, budget_usd=2.0),
+))
+personas = hs.list_personas()
+hs.update_persona(persona["id"], description="Updated")  # merge-patch
+
+# --- Agent roles in experiments ---
+exp = hs.create_experiment(experiment=Experiment(
+    name="Agent study",
+    runtime="v2",  # required for agent-only deployments
+    roles={"partner": Role(mode="agent", persona_id=persona["id"])},
+    agent_config=AgentConfig(seed=42),
+    states=[...],
+))
+
+# --- Agent-only deployment ---
+dep = hs.create_deployment(exp["id"], config={
+    "type": "agent-only",
+    "agentDeployment": {"rooms": 10, "budgetUsd": 5.0},
+})
+spend = hs.get_agent_spend(dep["id"])           # live spend vs budget
+hs.run_more(dep["id"], rooms=5, budget_usd=2.5) # additive batch
+
+# --- Agent data ---
+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": ...}
+```
+
+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
 
 ```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
+# ratings_continuous, ratings_sparse, components, eyetracking,
+# questionnaire, instructions, consent, agent_decisions
 ```
 
 ## API Key

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/README.md

@@ -43,6 +43,7 @@ chat          = hs.get_chat("exp_id")
 videochat     = hs.get_videochat("exp_id")
 sync          = hs.get_sync("exp_id")
 ratings       = hs.get_ratings("exp_id", kind="continuous")
+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 +52,13 @@ 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")
 ```
 
 ### Output Formats
@@ -95,6 +103,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+)
@@ -140,13 +151,60 @@ dep = hs.get_deployment("deployment_id")
 sessions = hs.get_deployment_sessions("deployment_id")
 ```
 
+## AI Agents
+
+Full agent workflow support: personas (the agent library), agent-role experiment authoring, agent-only deployment launch/control, and agent data.
+
+```python
+from hyperstudy import Persona, PromptLayer, Guardrails, Role, AgentConfig
+
+# --- Personas (agent library) ---
+persona = hs.create_persona(persona=Persona(
+    name="Curious Undergrad",
+    provider="anthropic",
+    model="claude-opus-4-8",
+    prompt=PromptLayer(persona="You are a curious undergraduate...",
+                       objective="Converse naturally with your partner."),
+    guardrails=Guardrails(max_turns=50, budget_usd=2.0),
+))
+personas = hs.list_personas()
+hs.update_persona(persona["id"], description="Updated")  # merge-patch
+
+# --- Agent roles in experiments ---
+exp = hs.create_experiment(experiment=Experiment(
+    name="Agent study",
+    runtime="v2",  # required for agent-only deployments
+    roles={"partner": Role(mode="agent", persona_id=persona["id"])},
+    agent_config=AgentConfig(seed=42),
+    states=[...],
+))
+
+# --- Agent-only deployment ---
+dep = hs.create_deployment(exp["id"], config={
+    "type": "agent-only",
+    "agentDeployment": {"rooms": 10, "budgetUsd": 5.0},
+})
+spend = hs.get_agent_spend(dep["id"])           # live spend vs budget
+hs.run_more(dep["id"], rooms=5, budget_usd=2.5) # additive batch
+
+# --- Agent data ---
+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": ...}
+```
+
+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
 
 ```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
+# ratings_continuous, ratings_sparse, components, eyetracking,
+# questionnaire, instructions, consent, agent_decisions
 ```
 
 ## API Key

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/pyproject.toml

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

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/src/hyperstudy/__init__.py

@@ -30,13 +30,17 @@ from .exceptions import (
     ValidationError,
 )
 from .models import (
+    AgentConfig,
     ComponentType,
     DisconnectTimeout,
     Experiment,
     FocusComponent,
     GlobalComponentType,
+    Guardrails,
     InstructionsPage,
+    Persona,
     PostExperimentQuestionnaire,
+    PromptLayer,
     Role,
     State,
     TransitionRules,
@@ -52,7 +56,7 @@ from .models import (
     waiting,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "HyperStudy",
@@ -75,6 +79,10 @@ __all__ = [
     "State",
     "FocusComponent",
     "Role",
+    "AgentConfig",
+    "PromptLayer",
+    "Persona",
+    "Guardrails",
     "TransitionRules",
     "WaitingRoomConfig",
     "DisconnectTimeout",

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/src/hyperstudy/_types.py

@@ -20,9 +20,12 @@ class DataType(str, Enum):
     VIDEOCHAT = "videochat"
     SYNC = "sync"
     RATINGS = "ratings"
+    EYETRACKING = "eyetracking"
     COMPONENTS = "components"
     PARTICIPANTS = "participants"
     ROOMS = "rooms"
+    AGENT_DECISIONS = "agentDecisions"
+    AGENT_RUNS = "agentRuns"
 
 
 class RatingKind(str, Enum):

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/src/hyperstudy/client.py

@@ -15,9 +15,10 @@ from ._pagination import fetch_all_pages
 from ._types import Scope
 from .exceptions import HyperStudyError
 from .experiments import ExperimentMixin
+from .personas import PersonaMixin
 
 
-class HyperStudy(ExperimentMixin):
+class HyperStudy(ExperimentMixin, PersonaMixin):
     """Client for the HyperStudy API v3.
 
     Args:
@@ -234,6 +235,35 @@ class HyperStudy(ExperimentMixin):
             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,
@@ -293,6 +323,67 @@ class HyperStudy(ExperimentMixin):
             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}
+        )
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data
+
     # ------------------------------------------------------------------
     # Convenience: category-filtered events
     # ------------------------------------------------------------------
@@ -441,6 +532,177 @@ class HyperStudy(ExperimentMixin):
         data = body.get("data", [])
         return self._convert_output(data, output)
 
+    # ------------------------------------------------------------------
+    # Deployments — agent-deployment write surface
+    # ------------------------------------------------------------------
+
+    def create_deployment(
+        self,
+        experiment_id: str,
+        *,
+        config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create a deployment (requires the ``write:deployments`` scope).
+
+        For an agent-only deployment, pass::
+
+            hs.create_deployment(
+                "exp_123",
+                config={
+                    "name": "Pilot batch",
+                    "type": "agent-only",
+                    "agentDeployment": {"rooms": 10, "budgetUsd": 5.0},
+                },
+            )
+
+        Agent rooms launch server-side immediately after creation. Preflight
+        failures (missing persona binding, missing provider key, unreachable
+        custom endpoint) raise :class:`ValidationError` with per-role reasons.
+
+        Args:
+            experiment_id: The experiment to deploy (agent-only requires
+                ``runtime="v2"`` and at least one agent-mode role).
+            config: Deployment config dict (camelCase keys, as above).
+            **kwargs: Extra config fields, merged into ``config``.
+
+        Returns:
+            The created deployment dict.
+        """
+        merged = {**(config or {}), **kwargs}
+        body = self._transport.post(
+            "deployments", json={"experimentId": experiment_id, "config": merged}
+        )
+        return body.get("data", {})
+
+    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", {})
+
+    def run_more(
+        self, deployment_id: str, *, rooms: int, budget_usd: float
+    ) -> dict[str, Any]:
+        """Launch additional agent rooms on an existing agent-only deployment.
+
+        Args:
+            deployment_id: The deployment to extend.
+            rooms: Number of additional rooms.
+            budget_usd: Additional budget for this batch (added to the
+                deployment's cumulative budget cap).
+
+        Returns:
+            Dict with the launched ``batchId`` and ``requestedRooms``.
+        """
+        body = self._transport.post(
+            f"deployments/{deployment_id}/run-more",
+            json={"rooms": rooms, "budgetUsd": budget_usd},
+        )
+        return body.get("data", {})
+
+    def stop_room(self, deployment_id: str, room_id: str) -> None:
+        """Force-end a running agent room."""
+        self._transport.post(f"deployments/{deployment_id}/rooms/{room_id}/stop")
+
+    def retry_room(self, deployment_id: str, room_id: str) -> dict[str, Any]:
+        """Re-spawn a fresh room for a spawn-failed one (reuses the budget pool)."""
+        body = self._transport.post(
+            f"deployments/{deployment_id}/rooms/{room_id}/retry"
+        )
+        return body.get("data", {})
+
+    # ------------------------------------------------------------------
+    # Agent data — decisions and run manifests
+    # ------------------------------------------------------------------
+
+    def get_agent_decisions(
+        self,
+        scope_id: str,
+        *,
+        scope: str = "experiment",
+        detail: bool = False,
+        limit: int | None = None,
+        participant_id: str | None = None,
+        output: str = "pandas",
+    ):
+        """Fetch AI-agent decision logs (and run manifests).
+
+        Every agent turn is logged as a decision record; each agent's run
+        also produces one manifest row. Room-scope responses tag rows with
+        ``_type`` (``"decision"`` or ``"run"``).
+
+        Args:
+            scope_id: Experiment ID or room ID, depending on ``scope``.
+            scope: ``"experiment"`` (default, all rooms) or ``"room"``.
+            detail: Include full detail blobs (prompt, reasoning chain,
+                peer-model snapshot, prediction update) on each decision row.
+            limit: Max decisions per room (server default 5000). When the
+                cap is hit a truncation warning is emitted.
+            participant_id: Optionally filter rows to one agent participant
+                (applied client-side).
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+        """
+        if scope not in ("experiment", "room"):
+            raise ValueError(f"scope must be 'experiment' or 'room', got {scope!r}")
+
+        params: dict[str, Any] = {}
+        if detail:
+            params["detail"] = "true"
+        if limit is not None:
+            params["limit"] = limit
+
+        body = self._transport.get(
+            f"data/agent-decisions/{scope}/{scope_id}", params=params or None
+        )
+        data = body.get("data", [])
+        if (body.get("metadata") or {}).get("truncated"):
+            warnings.warn(
+                "Agent decisions were truncated by the per-room limit; "
+                "pass a higher limit= to fetch more.",
+                stacklevel=2,
+            )
+        if participant_id is not None:
+            data = [row for row in data if row.get("participantId") == participant_id]
+        return self._convert_output(data, output)
+
+    def get_agent_decision(
+        self, room_id: str, decision_id: str
+    ) -> dict[str, Any]:
+        """Fetch one agent decision with full detail blobs.
+
+        Args:
+            room_id: Room the decision belongs to.
+            decision_id: Decision document ID (``{participantId}_{seq}``).
+
+        Returns:
+            Decision dict including prompt, reasoning chain, peer-model
+            snapshot, and prediction update.
+        """
+        body = self._transport.get(
+            f"data/agent-decisions/room/{room_id}/decision/{decision_id}"
+        )
+        return body.get("data", {})
+
+    def get_agent_runs(
+        self,
+        experiment_id: str,
+        *,
+        output: str = "pandas",
+    ):
+        """Fetch agent run manifests for an experiment.
+
+        One row per agent run: model, provider, token/cost totals, seed,
+        persona ID, and code version. Runs whose room ended abnormally are
+        flagged as orphaned.
+
+        Args:
+            experiment_id: Experiment ID.
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+        """
+        body = self._transport.get(f"data/agent-runs/experiment/{experiment_id}")
+        data = body.get("data", [])
+        return self._convert_output(data, output)
+
     # ------------------------------------------------------------------
     # Convenience: all data for a participant
     # ------------------------------------------------------------------
@@ -467,9 +729,13 @@ class HyperStudy(ExperimentMixin):
             "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),
             "questionnaire": self.get_questionnaire(participant_id, **common),
             "instructions": self.get_instructions(participant_id, **common),
             "consent": self.get_consent(participant_id, **common),
+            "agent_decisions": self.get_agent_decisions(
+                room_id, scope="room", participant_id=participant_id, output=output
+            ),
         }
 
     # ------------------------------------------------------------------

{hyperstudy-0.3.1 → hyperstudy-0.5.0}/src/hyperstudy/experiments.py

@@ -115,6 +115,17 @@ class ExperimentMixin:
         data = body.get("data", [])
         return data[0] if isinstance(data, list) and data else data
 
+    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")
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data
+
     # ------------------------------------------------------------------
     # Write
     # ------------------------------------------------------------------