hyperstudy 0.3.0__tar.gz → 0.4.0__tar.gz

hyperstudy-0.4.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+## 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
+
+- `download_recording` / `download_recordings` now mint a signed download URL via the recordings download endpoint (using each recording's `downloadPath`) and fall back to the legacy `downloadUrl`/`url` for older GCS-only recordings. Fixes downloads failing after the backend list endpoint stopped embedding signed URLs.
+
+### Fixes
+
+- Snake_case→camelCase conversion is now recursive for the raw-dict and `**kwargs` paths: nested keys (e.g. `waiting_room_config={"max_wait_time_ms": 5000}` → `{"waitingRoomConfig": {"maxWaitTimeMs": 5000}}`) and factory `**extra` kwargs are converted. Free-form map fields (`variables`, `roles`, `globalComponents`, `globalComponentsVisibility`) preserve their user-defined keys while still converting nested schema fields. Previously nested/extra snake_case keys were silently dropped on the wire.
+- Downloads are now atomic: each file streams to `<dest>.part` and is renamed on success, so a mid-stream failure never destroys a pre-existing complete file. `skip_existing` again skips when `fileSize` is unknown (an existing file is necessarily complete).
+- `update_experiment()` with no fields now raises `ValueError` instead of issuing an empty PUT.
+- `State.id` enforces `min_length=1`; `Experiment.global_components` keys are validated against `GlobalComponentType` (rejected at construction, still serialized as strings on the wire).
+- `FocusComponent.id` is auto-generated when omitted, including direct construction without a factory helper.
+
+
+## v0.3.0
+
+### Features
+
+- Typed experiment builders for programmatic authoring. New top-level exports: `Experiment`, `State`, `FocusComponent`, `Role`, `WaitingRoomConfig`, `DisconnectTimeout`, `InstructionsPage`, `PostExperimentQuestionnaire`, `TransitionRules`, `ComponentType`, `GlobalComponentType`. Snake_case Python fields are converted to the camelCase wire format automatically; unknown top-level fields are preserved via `extra="allow"` so the SDK doesn't block on backend schema additions.
+- Component factory helpers: `show_text`, `show_image`, `show_video`, `vas_rating`, `text_input`, `multiple_choice`, `waiting`, `likert_scale`, `ranking`. Extra kwargs pass through to the component `config` for any backend-supported field.
+- `create_experiment` and `update_experiment` now accept an `experiment=Experiment(...)` argument alongside the existing `**kwargs` form. When both are given, kwargs override builder fields.
+- New `validate_experiment(experiment)` method — dry-run against `POST /experiments/validate`.
+- Schema-drift guard test: vendored copy of `experiment.schema.json` is checked against `ComponentType` / `GlobalComponentType` / required-field declarations so backend additions surface in CI.
+
+### Backwards Compatibility
+
+- `create_experiment(name=..., **kwargs)` continues to work unchanged.
+- `update_experiment(experiment_id, **kwargs)` continues to work unchanged.
+
+### Dependencies
+
+- Adds `pydantic>=2.5`.
+
+## v0.2.0
+
+### Features
+
+- Convenience methods for common event categories: `get_questionnaire`, `get_instructions`, `get_consent`
+- Deployment management: `list_deployments`, `get_deployment`, `get_deployment_sessions`
+- API warning surfacing: backend `_warnings` metadata now emitted via Python's `warnings` module
+- `get_all_data` now includes `ratings_sparse`, `questionnaire`, `instructions`, and `consent`
+
+### Breaking Changes
+
+- `get_all_data` return keys changed: `"ratings"` split into `"ratings_continuous"` and `"ratings_sparse"`
+
+## v0.1.0
+
+Initial release.
+
+### Features
+
+- `HyperStudy` client with API key authentication (constructor arg or `HYPERSTUDY_API_KEY` env var)
+- Data retrieval methods: `get_events`, `get_recordings`, `get_chat`, `get_videochat`, `get_sync`, `get_ratings`, `get_components`, `get_participants`, `get_rooms`
+- `get_all_data` convenience method for fetching all data types for a single participant
+- Auto-pagination with `tqdm` progress bars (notebook and terminal)
+- Output format options: `"pandas"` (default), `"polars"`, `"dict"`
+- Experiment management: `list_experiments`, `get_experiment`, `get_experiment_config`, `create_experiment`, `update_experiment`, `delete_experiment`
+- Rich notebook display (`_repr_html_`) for experiment objects
+- Typed exceptions: `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `ServerError`
+- `health()` method for connection testing

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.3.0
+Version: 0.4.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
@@ -175,13 +175,57 @@ 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
+```
+
+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
+# instructions, consent, agent_decisions
 ```
 
 ## API Key

{hyperstudy-0.3.0 → hyperstudy-0.4.0}/README.md

@@ -140,13 +140,57 @@ 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
+```
+
+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
+# instructions, consent, agent_decisions
 ```
 
 ## API Key

{hyperstudy-0.3.0 → hyperstudy-0.4.0}/pyproject.toml

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

{hyperstudy-0.3.0 → hyperstudy-0.4.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.4.0"
 
 __all__ = [
     "HyperStudy",
@@ -75,6 +79,10 @@ __all__ = [
     "State",
     "FocusComponent",
     "Role",
+    "AgentConfig",
+    "PromptLayer",
+    "Persona",
+    "Guardrails",
     "TransitionRules",
     "WaitingRoomConfig",
     "DisconnectTimeout",

{hyperstudy-0.3.0 → hyperstudy-0.4.0}/src/hyperstudy/_downloads.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
 from typing import Any
@@ -38,12 +39,12 @@ def build_filename(recording: dict[str, Any]) -> str:
 
 
 def download_file(url: str, dest: Path, timeout: int = 300) -> int:
-    """Stream-download *url* to *dest* and return bytes written.
+    """Stream-download *url* to *dest*; returns bytes written.
 
-    Verifies ``Content-Length`` (when the server provides it) against bytes
-    actually written. On any error — HTTP, mid-stream disconnect, or length
-    mismatch — the partial file on disk is removed so ``skip_existing``
-    logic won't mistake it for a complete download on retry.
+    Downloads to a temporary ``<dest>.part`` and atomically renames on success, so a
+    mid-stream failure (HTTP error, disconnect, length mismatch) removes only the temp
+    file and leaves any pre-existing complete file at ``dest`` intact. Verifies
+    ``Content-Length`` when provided.
     """
     resp = requests.get(url, stream=True, timeout=timeout)
     resp.raise_for_status()
@@ -57,20 +58,23 @@ def download_file(url: str, dest: Path, timeout: int = 300) -> int:
     else:
         expected = None
 
+    tmp = dest.with_name(dest.name + ".part")
     written = 0
-    # BaseException so Ctrl-C also cleans up, not just exceptions.
     try:
-        with open(dest, "wb") as fh:
+        with open(tmp, "wb") as fh:
             for chunk in resp.iter_content(chunk_size=_CHUNK_SIZE):
                 fh.write(chunk)
                 written += len(chunk)
-
         if expected is not None and written != expected:
             raise IOError(
                 f"Truncated download: wrote {written} of {expected} bytes for {dest.name}"
             )
+        os.replace(tmp, dest)   # atomic on the same filesystem
     except BaseException:
-        dest.unlink(missing_ok=True)
+        try:
+            tmp.unlink(missing_ok=True)   # remove only the temp; never the existing dest
+        except OSError:
+            pass
         raise
 
     return written

{hyperstudy-0.3.0 → hyperstudy-0.4.0}/src/hyperstudy/_types.py

@@ -23,6 +23,8 @@ class DataType(str, Enum):
     COMPONENTS = "components"
     PARTICIPANTS = "participants"
     ROOMS = "rooms"
+    AGENT_DECISIONS = "agentDecisions"
+    AGENT_RUNS = "agentRuns"
 
 
 class RatingKind(str, Enum):

{hyperstudy-0.3.0 → hyperstudy-0.4.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:
@@ -441,6 +442,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
     # ------------------------------------------------------------------
@@ -470,12 +642,28 @@ class HyperStudy(ExperimentMixin):
             "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
+            ),
         }
 
     # ------------------------------------------------------------------
     # Recording downloads
     # ------------------------------------------------------------------
 
+    def _download_url_for(self, recording: dict[str, Any]) -> str | None:
+        """Resolve a directly-downloadable URL for a recording.
+
+        Prefers the auth'd mint endpoint (``downloadPath`` -> short-lived signed GCS
+        URL); falls back to a legacy absolute ``downloadUrl``/``url`` for old
+        GCS-only recordings.
+        """
+        download_path = recording.get("downloadPath")
+        if download_path:
+            body = self._transport.get(download_path)
+            return (body.get("data") or {}).get("url")
+        return get_download_url(recording)
+
     def download_recording(
         self,
         recording: dict[str, Any],
@@ -490,7 +678,7 @@ class HyperStudy(ExperimentMixin):
         Returns:
             Path to the downloaded file.
         """
-        url = get_download_url(recording)
+        url = self._download_url_for(recording)
         if not url:
             raise ValueError("Recording has no downloadUrl or url field")
 
@@ -564,27 +752,30 @@ class HyperStudy(ExperimentMixin):
 
         local_paths: list[str | None] = []
         statuses: list[str] = []
+        failed_count = 0
 
         for rec in tqdm(recordings, desc="Downloading recordings", disable=not progress):
             filename = build_filename(rec)
             dest = dest_dir / filename
 
-            url = get_download_url(rec)
-            if not url:
-                local_paths.append(None)
-                statuses.append("failed")
-                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
-                continue
-
+            # Check skip before resolving the URL (avoids minting a signed URL unnecessarily).
             if skip_existing and dest.exists():
                 expected_size = rec.get("fileSize")
-                # Require positive size match; missing size → re-download to
-                # avoid trusting a truncated file from a prior failed run.
-                if expected_size is not None and dest.stat().st_size == expected_size:
+                # dest is always a fully-written file (atomic rename), so skip when size is
+                # unknown OR matches; only re-download on a definite size mismatch.
+                if expected_size is None or dest.stat().st_size == expected_size:
                     local_paths.append(str(dest.resolve()))
                     statuses.append("skipped")
                     continue
 
+            url = self._download_url_for(rec)
+            if not url:
+                local_paths.append(None)
+                statuses.append("failed")
+                failed_count += 1
+                warnings.warn(f"Recording {rec.get('recordingId')} has no download URL")
+                continue
+
             try:
                 download_file(url, dest)
                 local_paths.append(str(dest.resolve()))
@@ -592,11 +783,11 @@ class HyperStudy(ExperimentMixin):
             except Exception as exc:
                 local_paths.append(None)
                 statuses.append("failed")
+                failed_count += 1
                 warnings.warn(
                     f"Failed to download recording {rec.get('recordingId')}: {exc}"
                 )
 
-        failed_count = sum(1 for s in statuses if s == "failed")
         if failed_count:
             warnings.warn(
                 f"{failed_count}/{len(recordings)} recordings failed to download; "

{hyperstudy-0.3.0 → hyperstudy-0.4.0}/src/hyperstudy/experiments.py

@@ -10,6 +10,7 @@ from pydantic.alias_generators import to_camel
 from ._display import ExperimentInfo
 from ._http import HttpTransport
 from ._pagination import fetch_all_pages
+from .models import camelize_wire
 
 if TYPE_CHECKING:
     from .models import Experiment
@@ -37,13 +38,14 @@ def _build_experiment_payload(
     elif isinstance(experiment, BaseModel):
         payload = experiment.model_dump(by_alias=True, exclude_none=True)
     elif isinstance(experiment, dict):
-        payload = dict(experiment)
+        payload = camelize_wire(experiment)
     else:
         raise TypeError(
             f"experiment must be an Experiment or dict, got {type(experiment).__name__}"
         )
     for key, value in overrides.items():
-        payload[to_camel(key)] = value
+        ck = to_camel(key)
+        payload[ck] = camelize_wire(value, _parent_key=ck)
     return payload
 
 
@@ -182,6 +184,11 @@ class ExperimentMixin:
             Update confirmation dict.
         """
         payload = _build_experiment_payload(experiment, **kwargs)
+        if not payload:
+            raise ValueError(
+                "update_experiment requires at least one field to update "
+                "(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