hyperstudy 0.3.1__tar.gz → 0.4.0__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperstudy
-Version: 0.3.1
+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.1 → 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.1 → hyperstudy-0.4.0}/pyproject.toml

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

{hyperstudy-0.3.1 → 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.1 → 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.1 → 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,6 +642,9 @@ 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
+            ),
         }
 
     # ------------------------------------------------------------------

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

@@ -26,6 +26,7 @@ def _new_id() -> str:
 # Their values are still recursed into.
 _FREEFORM_MAP_FIELDS = frozenset({
     "variables", "roles", "globalComponents", "globalComponentsVisibility",
+    "roleOverrides",
 })
 
 
@@ -132,10 +133,84 @@ class State(_Model):
 
 
 class Role(_Model):
-    """Participant role definition for multi-participant experiments."""
+    """Participant role definition for multi-participant experiments.
+
+    Set ``mode="agent"`` and ``persona_id`` to have an AI agent (persona
+    from your library) fill this role instead of a human participant.
+    """
 
     name: Optional[str] = None
     participant_count: Optional[int] = Field(default=None, ge=0)
+    mode: Optional[str] = None  # "human" (default) or "agent"
+    persona_id: Optional[str] = None
+
+
+class PromptLayer(_Model):
+    """Structured prompt fields, used for per-role agent overrides.
+
+    Overrides are APPENDED to the bound persona's own prompt fields —
+    they never replace the persona's identity.
+    """
+
+    persona: Optional[str] = None
+    objective: Optional[str] = None
+    guidance: Optional[str] = None
+    examples: Optional[list[str]] = None
+    additional_instructions: Optional[str] = None
+
+
+class AgentConfig(_Model):
+    """Experiment-level agent inputs.
+
+    The bound persona is the source of truth for provider/model/prompt;
+    the experiment contributes only per-role prompt overrides, pacing,
+    and the random seed.
+    """
+
+    role_overrides: Optional[dict[str, PromptLayer]] = None
+    pacing: Optional[dict[str, Any]] = None
+    seed: Optional[int] = None
+
+
+class Guardrails(_Model):
+    """Per-agent safety limits. Unset fields use platform defaults
+    (100 turns / 500k tokens); budgets fail closed when exceeded."""
+
+    max_turns: Optional[int] = Field(default=None, ge=1)
+    budget_tokens: Optional[int] = Field(default=None, ge=1000)
+    budget_usd: Optional[float] = Field(default=None, gt=0)
+    max_consecutive_decision_errors: Optional[int] = Field(default=None, ge=1)
+
+
+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.
+    """
+
+    name: str = Field(min_length=1)
+    description: Optional[str] = None
+    prompt: Optional[PromptLayer] = None
+    provider: Optional[str] = None  # anthropic (default) | openai | gemini | custom
+    model: Optional[str] = None  # required when provider == "custom"
+    temperature: Optional[float] = None
+    top_p: Optional[float] = None
+    max_tokens: Optional[int] = None
+    thinking: Optional[bool] = None
+    reasoning_effort: Optional[str] = None
+    extra_params: Optional[dict[str, Any]] = None
+    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
+    guardrails: Optional[Guardrails] = None
+    pacing: Optional[dict[str, Any]] = None
+    visibility: Optional[str] = None  # create-time only: private | organization | public
 
 
 class WaitingRoomConfig(_Model):
@@ -170,6 +245,8 @@ class Experiment(_Model):
     name: str = Field(min_length=1)
     description: Optional[str] = None
     required_participants: Optional[int] = Field(default=None, ge=1)
+    runtime: Optional[str] = None  # "v2" required for agent-only deployments
+    agent_config: Optional[AgentConfig] = None
     randomize_states: Optional[bool] = None
     states: Optional[list[State]] = None
     roles: Optional[dict[str, Role]] = None

hyperstudy-0.4.0/src/hyperstudy/personas.py

@@ -0,0 +1,103 @@
+"""Persona (agent library) methods, mixed into the HyperStudy client.
+
+Personas are reusable AI-agent definitions. These methods target the
+/api/v3/personas routes and require API-key scopes ``read:personas`` /
+``write:personas``.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .models import Persona
+
+
+def _persona_payload(persona: "Persona | None", kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Build a wire-ready persona payload from a typed Persona and/or kwargs."""
+    from .models import Persona as PersonaModel
+    from .models import camelize_wire
+
+    payload: dict[str, Any] = {}
+    if persona is not None:
+        if not isinstance(persona, PersonaModel):
+            raise TypeError("persona must be a hyperstudy.Persona instance")
+        payload.update(persona.model_dump(by_alias=True, exclude_none=True))
+    if kwargs:
+        payload.update(camelize_wire(kwargs))
+    return payload
+
+
+class PersonaMixin:
+    """Persona CRUD methods for the HyperStudy client."""
+
+    def list_personas(self, *, output: str = "pandas"):
+        """List personas you own or can view (organization-scoped).
+
+        Args:
+            output: ``"pandas"`` (default), ``"polars"``, or ``"dict"``.
+        """
+        body = self._transport.get("personas")
+        return self._convert_output(body.get("data", []), output)
+
+    def get_persona(self, persona_id: str) -> dict[str, Any]:
+        """Get one persona by ID."""
+        body = self._transport.get(f"personas/{persona_id}")
+        return body.get("data", {})
+
+    def create_persona(
+        self,
+        *,
+        persona: "Persona | None" = None,
+        name: str | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create a persona.
+
+        Two equivalent ways to call this:
+
+        - **Typed builder** (recommended): pass a :class:`Persona` instance.
+        - **Kwargs**: pass snake_case fields directly
+          (``create_persona(name="Confederate", provider="anthropic", ...)``).
+
+        Returns:
+            The created persona (including its ``id``).
+        """
+        if name is not None:
+            kwargs["name"] = name
+        payload = _persona_payload(persona, kwargs)
+        if not payload.get("name"):
+            raise ValueError("Persona name is required")
+        body = self._transport.post("personas", json=payload)
+        return body.get("data", {})
+
+    def update_persona(
+        self,
+        persona_id: str,
+        *,
+        persona: "Persona | None" = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Update a persona (merge-patch).
+
+        Only the fields you pass are changed; everything else on the stored
+        persona is preserved.
+        """
+        payload = _persona_payload(persona, kwargs)
+        if not payload:
+            raise ValueError("No fields to update")
+        body = self._transport.put(f"personas/{persona_id}", json=payload)
+        return body.get("data", {})
+
+    def delete_persona(self, persona_id: str) -> None:
+        """Delete a persona."""
+        self._transport.delete(f"personas/{persona_id}")
+
+    def duplicate_persona(self, persona_id: str) -> dict[str, Any]:
+        """Copy a viewable persona into a new private persona you own.
+
+        Returns:
+            The new persona (named ``"<original name> (copy)"``).
+        """
+        body = self._transport.post(f"personas/{persona_id}/duplicate")
+        return body.get("data", {})

hyperstudy-0.4.0/tests/fixtures/agent_decision_detail_response.json

@@ -0,0 +1,30 @@
+{
+  "status": "success",
+  "data": {
+    "id": "agent_r1_p1_2",
+    "participantId": "agent_r1_p1",
+    "roomId": "room_abc123",
+    "seq": 2,
+    "stateId": "state_1",
+    "stateName": "Rating",
+    "turnKind": "component",
+    "action": "respond",
+    "value": 72,
+    "model": "claude-opus-4-8",
+    "provider": "anthropic",
+    "prompt": "You are a curious undergraduate...\n\nCurrent situation: ...",
+    "reasoning": "The video felt moderately positive, so I will rate 72.",
+    "chain": [
+      {"stage": "goal_infer", "output": "Partner seems to want agreement."},
+      {"stage": "decide", "output": "respond(72)"}
+    ],
+    "peerModelSnapshot": {"peer_1": {"inferredGoal": "agreement"}},
+    "predictionUpdate": {"predictionError": 0.18},
+    "timestamp": "2026-07-15T18:23:04.000Z"
+  },
+  "metadata": {
+    "dataType": "agentDecisions",
+    "scope": "room",
+    "scopeId": "room_abc123"
+  }
+}