hyperstudy 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,5 +1,19 @@
 # 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.4.0
+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+)
@@ -215,6 +226,9 @@ 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": ...}
 ```
 
 Persona methods need the `read:personas` / `write:personas` API-key scopes; deployment launch/control needs `write:deployments`; agent data reads need `read:events`.
@@ -224,8 +238,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,
+# questionnaire, instructions, consent, agent_decisions
 ```
 
 ## API Key

{hyperstudy-0.4.0 → 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+)
@@ -180,6 +191,9 @@ 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": ...}
 ```
 
 Persona methods need the `read:personas` / `write:personas` API-key scopes; deployment launch/control needs `write:deployments`; agent data reads need `read:events`.
@@ -189,8 +203,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,
+# questionnaire, instructions, consent, agent_decisions
 ```
 
 ## API Key

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

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

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

@@ -56,7 +56,7 @@ from .models import (
     waiting,
 )
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "HyperStudy",

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

@@ -20,6 +20,7 @@ class DataType(str, Enum):
     VIDEOCHAT = "videochat"
     SYNC = "sync"
     RATINGS = "ratings"
+    EYETRACKING = "eyetracking"
     COMPONENTS = "components"
     PARTICIPANTS = "participants"
     ROOMS = "rooms"

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

@@ -235,6 +235,35 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             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,
@@ -294,6 +323,67 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             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
     # ------------------------------------------------------------------
@@ -639,6 +729,7 @@ class HyperStudy(ExperimentMixin, PersonaMixin):
             "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),

{hyperstudy-0.4.0 → 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
     # ------------------------------------------------------------------

{hyperstudy-0.4.0 → hyperstudy-0.5.0}/src/hyperstudy/models.py

@@ -186,8 +186,9 @@ class Persona(_Model):
     """A reusable AI-agent definition (agent library entry).
 
     The persona owns the agent's identity, model settings, guardrails and
-    (optionally) cognition. ``cognition`` / ``offline_cognition`` are accepted
-    as plain dicts — their schema is experimental and still evolving.
+    (optionally) cognition. ``cognition`` is accepted as a plain dict — its
+    schema is experimental and still evolving. Offline loops live inside
+    ``cognition["config"]["contexts"][<name>]["offline"]``.
     """
 
     name: str = Field(min_length=1)
@@ -204,7 +205,6 @@ class Persona(_Model):
     disable_thinking: Optional[bool] = None
     seed: Optional[int] = None
     cognition: Optional[dict[str, Any]] = None
-    offline_cognition: Optional[dict[str, Any]] = None
     memory_persistence: Optional[str] = None  # "none" (default) | "cross-experiment"
     language: Optional[str] = None
     seed_memories: Optional[list[dict[str, Any]]] = None

{hyperstudy-0.4.0 → hyperstudy-0.5.0}/src/hyperstudy/personas.py

@@ -25,6 +25,11 @@ def _persona_payload(persona: "Persona | None", kwargs: dict[str, Any]) -> dict[
         payload.update(persona.model_dump(by_alias=True, exclude_none=True))
     if kwargs:
         payload.update(camelize_wire(kwargs))
+    # The server hard-discards offlineCognition (offline loops now live inside
+    # cognition.config.contexts.<name>.offline), so never send it — including
+    # when a Persona was rebuilt from an older API response via extra fields.
+    payload.pop("offlineCognition", None)
+    payload.pop("offline_cognition", None)
     return payload
 
 
@@ -101,3 +106,16 @@ class PersonaMixin:
         """
         body = self._transport.post(f"personas/{persona_id}/duplicate")
         return body.get("data", {})
+
+    def get_cognition_catalog(self) -> dict[str, Any]:
+        """Fetch the cognition authoring catalog.
+
+        Lists the valid building blocks for persona ``cognition`` configs.
+        Requires the ``read:personas`` scope.
+
+        Returns:
+            Dict with ``abilities``, ``recipes``, and ``offlineRecipes``.
+        """
+        body = self._transport.get("agent-cognition/catalog")
+        data = body.get("data", [])
+        return data[0] if isinstance(data, list) and data else data

{hyperstudy-0.4.0 → hyperstudy-0.5.0}/tests/test_client.py

@@ -242,6 +242,126 @@ def test_get_ratings_sparse_flattens_data(api_key, sparse_ratings_response):
     assert df["sparseRatingData_mediaPauseOnset"].iloc[0] == 8200
 
 
+@responses.activate
+def test_get_eyetracking(api_key, events_response):
+    """get_eyetracking hits the correct endpoint."""
+    responses.get(
+        f"{BASE_URL}/data/eyetracking/experiment/exp_abc123",
+        json=events_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_eyetracking("exp_abc123", limit=1000)
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 3
+
+
+@responses.activate
+def test_get_eyetracking_participant_scope(api_key, events_response):
+    """get_eyetracking with scope='participant' passes roomId query param."""
+    responses.get(
+        f"{BASE_URL}/data/eyetracking/participant/user_1",
+        json=events_response,
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    df = client.get_eyetracking(
+        "user_1", scope="participant", room_id="room_xyz", limit=1000
+    )
+    assert len(df) == 3
+    assert "roomId=room_xyz" in responses.calls[0].request.url
+
+
+@responses.activate
+def test_get_variables(api_key):
+    """get_variables returns writes, timeline, variable names, and dropped writes."""
+    responses.get(
+        f"{BASE_URL}/data/variables/room/room_xyz",
+        json={
+            "status": "success",
+            "data": [
+                {"variable": "rating", "value": 7, "source": "human", "persisted": True},
+                {"variable": "condition", "value": "A", "source": "seed", "persisted": True},
+            ],
+            "metadata": {
+                "variableNames": ["condition", "rating"],
+                "timeline": [{"stateId": "s1", "condition": "A", "rating": 7}],
+                "matrixColumns": ["stateId", "condition", "rating"],
+                "droppedWrites": [{"variable": "rating", "reason": "mismatch"}],
+                "mode": "replay",
+            },
+        },
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    result = client.get_variables("room_xyz")
+
+    assert isinstance(result["writes"], pd.DataFrame)
+    assert len(result["writes"]) == 2
+    assert set(result["writes"]["variable"]) == {"rating", "condition"}
+    assert isinstance(result["timeline"], pd.DataFrame)
+    assert len(result["timeline"]) == 1
+    assert result["variable_names"] == ["condition", "rating"]
+    assert result["matrix_columns"] == ["stateId", "condition", "rating"]
+    assert result["dropped_writes"] == [{"variable": "rating", "reason": "mismatch"}]
+    assert result["mode"] == "replay"
+
+
+@responses.activate
+def test_get_variables_dict(api_key):
+    """get_variables with output='dict' returns raw write and timeline lists."""
+    responses.get(
+        f"{BASE_URL}/data/variables/room/room_xyz",
+        json={
+            "status": "success",
+            "data": [{"variable": "rating", "value": 7}],
+            "metadata": {},
+        },
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    result = client.get_variables("room_xyz", output="dict")
+    assert result["writes"] == [{"variable": "rating", "value": 7}]
+    assert result["timeline"] == []
+    assert result["variable_names"] == []
+    assert result["dropped_writes"] == []
+
+
+@responses.activate
+def test_get_counts(api_key):
+    """get_counts passes roomId and unwraps the counts dict."""
+    responses.get(
+        f"{BASE_URL}/data/counts/participant/user_1",
+        json={
+            "status": "success",
+            "data": [
+                {
+                    "participantId": "user_1",
+                    "roomId": "room_xyz",
+                    "counts": {"textchat": 4, "sync": 0},
+                    "hasData": {"textchat": True, "sync": False},
+                }
+            ],
+            "metadata": {},
+        },
+        status=200,
+    )
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    result = client.get_counts("user_1", room_id="room_xyz")
+
+    assert isinstance(result, dict)
+    assert result["counts"]["textchat"] == 4
+    assert result["hasData"]["sync"] is False
+    assert "roomId=room_xyz" in responses.calls[0].request.url
+
+
+def test_get_counts_requires_room_id(api_key):
+    """get_counts requires room_id (the server 400s without it)."""
+    client = HyperStudy(api_key=api_key, base_url=BASE_URL)
+    with pytest.raises(TypeError):
+        client.get_counts("user_1")
+
+
 @responses.activate
 def test_get_sync_with_aggregation(api_key, events_response):
     """get_sync passes aggregationWindow param."""
@@ -519,7 +639,8 @@ def test_get_all_data(api_key, events_response, pre_experiment_response):
     """get_all_data returns a dict of DataFrames."""
     # Mock all data type endpoints for participant scope
     for dtype in ("events", "recordings", "chat", "videochat", "sync",
-                  "ratings/continuous", "ratings/sparse", "components"):
+                  "ratings/continuous", "ratings/sparse", "components",
+                  "eyetracking"):
         responses.get(
             f"{BASE_URL}/data/{dtype}/participant/user_1",
             json=events_response,
@@ -541,7 +662,7 @@ def test_get_all_data(api_key, events_response, pre_experiment_response):
     assert isinstance(result, dict)
     assert set(result.keys()) == {
         "events", "recordings", "chat", "videochat", "sync",
-        "ratings_continuous", "ratings_sparse", "components",
+        "ratings_continuous", "ratings_sparse", "components", "eyetracking",
         "questionnaire", "instructions", "consent", "agent_decisions",
     }
     for v in result.values():

{hyperstudy-0.4.0 → hyperstudy-0.5.0}/tests/test_experiments.py

@@ -99,6 +99,38 @@ def test_get_experiment_config(experiment_single_response):
     assert config["id"] == "exp_abc123"
 
 
+@responses.activate
+def test_export_experiment():
+    """export_experiment returns the portable experiment JSON."""
+    export_response = {
+        "status": "success",
+        "metadata": {
+            "dataType": "experimentExport",
+            "scope": "experiment",
+            "scopeId": "exp_abc123",
+            "filename": "emotion-study-export.json",
+            "mediaAssetsCount": 2,
+        },
+        "data": [
+            {
+                "experiment": {"name": "Emotion Study", "states": []},
+                "mediaAssets": [{"url": "https://cdn.example.com/clip.mp4"}],
+            }
+        ],
+    }
+    responses.get(
+        f"{BASE_URL}/experiments/exp_abc123/export",
+        json=export_response,
+        status=200,
+    )
+    client = HyperStudy(api_key="hst_test_key", base_url=BASE_URL)
+    export = client.export_experiment("exp_abc123")
+
+    assert isinstance(export, dict)
+    assert export["experiment"]["name"] == "Emotion Study"
+    assert len(export["mediaAssets"]) == 1
+
+
 @responses.activate
 def test_create_experiment():
     """create_experiment POSTs to the experiments endpoint."""

{hyperstudy-0.4.0 → hyperstudy-0.5.0}/tests/test_personas.py

@@ -112,6 +112,76 @@ def test_update_persona_requires_fields(api_key):
         client.update_persona("persona-1")
 
 
+@responses.activate
+def test_create_persona_strips_offline_cognition(api_key):
+    """offlineCognition is never sent — the server hard-discards it.
+
+    Covers both a Persona rebuilt from an older API response (extra field)
+    and the snake_case kwargs path. Offline loops now live inside
+    cognition.config.contexts.<name>.offline."""
+    responses.post(f"{BASE_URL}/personas", json=_envelope(PERSONA_DOC), status=201)
+    responses.post(f"{BASE_URL}/personas", json=_envelope(PERSONA_DOC), status=201)
+
+    client = HyperStudy(api_key=api_key)
+
+    # Persona rebuilt from an older response doc carrying offlineCognition.
+    persona = Persona(**{
+        "name": "Rebuilt",
+        "cognition": {"config": {"contexts": {"social": {"offline": {"cadence": "endOfState"}}}}},
+        "offlineCognition": {"loops": []},
+    })
+    client.create_persona(persona=persona)
+    sent = json.loads(responses.calls[0].request.body)
+    assert "offlineCognition" not in sent
+    assert "offline_cognition" not in sent
+    assert sent["cognition"]["config"]["contexts"]["social"]["offline"] == {
+        "cadence": "endOfState"
+    }
+
+    # Snake_case kwargs path.
+    client.create_persona(name="Kwargs", offline_cognition={"loops": []})
+    sent = json.loads(responses.calls[1].request.body)
+    assert "offlineCognition" not in sent
+    assert "offline_cognition" not in sent
+
+
+@responses.activate
+def test_update_persona_strips_offline_cognition(api_key):
+    """update_persona also drops offlineCognition from the payload."""
+    responses.put(f"{BASE_URL}/personas/persona-1", json=_envelope(PERSONA_DOC), status=200)
+
+    client = HyperStudy(api_key=api_key)
+    client.update_persona("persona-1", description="Updated", offline_cognition={"loops": []})
+
+    sent = json.loads(responses.calls[0].request.body)
+    assert sent == {"description": "Updated"}
+
+
+def test_persona_model_has_no_offline_cognition_field():
+    """The typed Persona model no longer declares offline_cognition."""
+    assert "offline_cognition" not in Persona.model_fields
+
+
+@responses.activate
+def test_get_cognition_catalog(api_key):
+    """get_cognition_catalog returns the abilities/recipes/offlineRecipes dict."""
+    catalog = {
+        "abilities": {"perceive": {"description": "..."}},
+        "recipes": {"default": ["perceive"]},
+        "offlineRecipes": {"consolidate": ["reflect"]},
+    }
+    # The v3 envelope array-wraps non-array data; the client unwraps it.
+    responses.get(
+        f"{BASE_URL}/agent-cognition/catalog", json=_envelope([catalog]), status=200
+    )
+
+    client = HyperStudy(api_key=api_key)
+    result = client.get_cognition_catalog()
+
+    assert result == catalog
+    assert set(result.keys()) == {"abilities", "recipes", "offlineRecipes"}
+
+
 @responses.activate
 def test_delete_and_duplicate_persona(api_key):
     responses.delete(f"{BASE_URL}/personas/persona-1", json=_envelope({"deleted": True}), status=200)