hyperstudy 0.1.0__tar.gz

hyperstudy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hyperstudy-0.1.0/.github/workflows/sync-release-notes.yml

@@ -0,0 +1,67 @@
+name: Sync Release Notes to Docs
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Get release info
+        id: release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ github.event.release.tag_name }}"
+          echo "tag=$TAG" >> $GITHUB_OUTPUT
+
+          BODY=$(gh release view "$TAG" --repo ${{ github.repository }} --json body -q '.body')
+          echo "body<<EOF" >> $GITHUB_OUTPUT
+          echo "$BODY" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Checkout hyperstudy-docs
+        uses: actions/checkout@v4
+        with:
+          repository: ljchang/hyperstudy-docs
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          path: docs-repo
+
+      - name: Create release notes
+        run: |
+          cd docs-repo
+          TAG="${{ steps.release.outputs.tag }}"
+          DIR="docs/release-notes/python-sdk"
+          FILE="$DIR/${TAG}.md"
+
+          mkdir -p "$DIR"
+
+          cat > "$FILE" << EOF
+          ---
+          title: Python SDK ${TAG}
+          ---
+
+          # Python SDK ${TAG}
+
+          Released: $(date -u +"%Y-%m-%d")
+
+          ${{ steps.release.outputs.body }}
+          EOF
+
+          # Remove leading whitespace from heredoc
+          sed -i 's/^          //' "$FILE"
+
+      - name: Create PR to hyperstudy-docs
+        uses: peter-evans/create-pull-request@v6
+        with:
+          path: docs-repo
+          token: ${{ secrets.DOCS_REPO_TOKEN }}
+          title: "docs: Python SDK ${{ steps.release.outputs.tag }} release notes"
+          branch: "python-sdk-release-${{ steps.release.outputs.tag }}"
+          commit-message: "Add Python SDK ${{ steps.release.outputs.tag }} release notes"
+          body: |
+            Auto-generated release notes for Python SDK ${{ steps.release.outputs.tag }}.
+
+            Source: ${{ github.event.release.html_url }}

hyperstudy-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev,polars]"
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Run tests
+        run: pytest --cov=hyperstudy --cov-report=term-missing -v

hyperstudy-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.venv/
+venv/
+*.whl
+.DS_Store

hyperstudy-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luke Chang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hyperstudy-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: hyperstudy
+Version: 0.1.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
+Project-URL: Repository, https://github.com/ljchang/hyperstudy-pythonsdk
+Project-URL: Issues, https://github.com/ljchang/hyperstudy-pythonsdk/issues
+Author-email: Luke Chang <luke.j.chang@dartmouth.edu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20.0; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# hyperstudy
+
+Python SDK for the [HyperStudy](https://hyperstudy.io) experiment platform API. Designed for researchers working in Jupyter, marimo, or Python scripts.
+
+## Installation
+
+```bash
+pip install hyperstudy
+```
+
+For polars support:
+
+```bash
+pip install hyperstudy[polars]
+```
+
+## Quick Start
+
+```python
+import hyperstudy
+
+hs = hyperstudy.HyperStudy(api_key="hst_live_...")
+# Or set the HYPERSTUDY_API_KEY environment variable
+
+# Fetch events as a pandas DataFrame
+events = hs.get_events("your_experiment_id")
+
+# Room-scoped data
+events = hs.get_events("room_id", scope="room")
+
+# Participant-scoped data
+events = hs.get_events("participant_id", scope="participant", room_id="room_id")
+```
+
+## Data Types
+
+All data retrieval methods follow the same pattern:
+
+```python
+events      = hs.get_events("exp_id")
+recordings  = hs.get_recordings("exp_id")
+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")
+components  = hs.get_components("exp_id")
+participants = hs.get_participants("exp_id")
+rooms       = hs.get_rooms("exp_id")
+```
+
+### Output Formats
+
+```python
+df_pandas = hs.get_events("exp_id")                      # pandas (default)
+df_polars = hs.get_events("exp_id", output="polars")     # polars
+raw       = hs.get_events("exp_id", output="dict")       # list[dict]
+```
+
+### Filtering
+
+```python
+events = hs.get_events(
+    "exp_id",
+    start_time="2024-01-01T10:00:00Z",
+    end_time="2024-01-01T12:00:00Z",
+    category="component",
+    sort="onset",
+    limit=100,
+)
+```
+
+### Auto-Pagination
+
+When `limit` is not set, all pages are fetched automatically with a progress bar:
+
+```python
+all_events = hs.get_events("exp_id")  # fetches all pages
+```
+
+## Experiment Management
+
+```python
+# List experiments
+experiments = hs.list_experiments()
+
+# Get details (with rich display in notebooks)
+exp = hs.get_experiment("exp_id")
+
+# Create / update / delete
+new_exp = hs.create_experiment(name="My Study", description="...")
+hs.update_experiment("exp_id", name="Updated Name")
+hs.delete_experiment("exp_id")
+```
+
+## All Data for a Participant
+
+```python
+data = hs.get_all_data("participant_id", room_id="room_id")
+# Returns: {"events": DataFrame, "recordings": DataFrame, "chat": DataFrame, ...}
+```
+
+## API Key
+
+Generate an API key from the HyperStudy dashboard under Settings. Keys follow the format `hst_{environment}_{key}` and are passed via the `X-API-Key` header.
+
+## Documentation
+
+Full documentation: [docs.hyperstudy.io/developers/python-sdk](https://docs.hyperstudy.io/developers/python-sdk)
+
+## Development
+
+```bash
+git clone https://github.com/ljchang/hyperstudy-pythonsdk.git
+cd hyperstudy-pythonsdk
+pip install -e ".[dev,polars]"
+pytest --cov=hyperstudy
+ruff check src/
+```
+
+## License
+
+MIT

hyperstudy-0.1.0/README.md

@@ -0,0 +1,122 @@
+# hyperstudy
+
+Python SDK for the [HyperStudy](https://hyperstudy.io) experiment platform API. Designed for researchers working in Jupyter, marimo, or Python scripts.
+
+## Installation
+
+```bash
+pip install hyperstudy
+```
+
+For polars support:
+
+```bash
+pip install hyperstudy[polars]
+```
+
+## Quick Start
+
+```python
+import hyperstudy
+
+hs = hyperstudy.HyperStudy(api_key="hst_live_...")
+# Or set the HYPERSTUDY_API_KEY environment variable
+
+# Fetch events as a pandas DataFrame
+events = hs.get_events("your_experiment_id")
+
+# Room-scoped data
+events = hs.get_events("room_id", scope="room")
+
+# Participant-scoped data
+events = hs.get_events("participant_id", scope="participant", room_id="room_id")
+```
+
+## Data Types
+
+All data retrieval methods follow the same pattern:
+
+```python
+events      = hs.get_events("exp_id")
+recordings  = hs.get_recordings("exp_id")
+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")
+components  = hs.get_components("exp_id")
+participants = hs.get_participants("exp_id")
+rooms       = hs.get_rooms("exp_id")
+```
+
+### Output Formats
+
+```python
+df_pandas = hs.get_events("exp_id")                      # pandas (default)
+df_polars = hs.get_events("exp_id", output="polars")     # polars
+raw       = hs.get_events("exp_id", output="dict")       # list[dict]
+```
+
+### Filtering
+
+```python
+events = hs.get_events(
+    "exp_id",
+    start_time="2024-01-01T10:00:00Z",
+    end_time="2024-01-01T12:00:00Z",
+    category="component",
+    sort="onset",
+    limit=100,
+)
+```
+
+### Auto-Pagination
+
+When `limit` is not set, all pages are fetched automatically with a progress bar:
+
+```python
+all_events = hs.get_events("exp_id")  # fetches all pages
+```
+
+## Experiment Management
+
+```python
+# List experiments
+experiments = hs.list_experiments()
+
+# Get details (with rich display in notebooks)
+exp = hs.get_experiment("exp_id")
+
+# Create / update / delete
+new_exp = hs.create_experiment(name="My Study", description="...")
+hs.update_experiment("exp_id", name="Updated Name")
+hs.delete_experiment("exp_id")
+```
+
+## All Data for a Participant
+
+```python
+data = hs.get_all_data("participant_id", room_id="room_id")
+# Returns: {"events": DataFrame, "recordings": DataFrame, "chat": DataFrame, ...}
+```
+
+## API Key
+
+Generate an API key from the HyperStudy dashboard under Settings. Keys follow the format `hst_{environment}_{key}` and are passed via the `X-API-Key` header.
+
+## Documentation
+
+Full documentation: [docs.hyperstudy.io/developers/python-sdk](https://docs.hyperstudy.io/developers/python-sdk)
+
+## Development
+
+```bash
+git clone https://github.com/ljchang/hyperstudy-pythonsdk.git
+cd hyperstudy-pythonsdk
+pip install -e ".[dev,polars]"
+pytest --cov=hyperstudy
+ruff check src/
+```
+
+## License
+
+MIT

hyperstudy-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hyperstudy"
+version = "0.1.0"
+description = "Python SDK for the HyperStudy experiment platform API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "Luke Chang", email = "luke.j.chang@dartmouth.edu" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "pandas>=1.5.0",
+    "tqdm>=4.60.0",
+]
+
+[project.optional-dependencies]
+polars = ["polars>=0.20.0"]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "responses>=0.23.0",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://hyperstudy.io"
+Documentation = "https://docs.hyperstudy.io/developers/python-sdk"
+Repository = "https://github.com/ljchang/hyperstudy-pythonsdk"
+Issues = "https://github.com/ljchang/hyperstudy-pythonsdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperstudy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]

hyperstudy-0.1.0/src/hyperstudy/__init__.py

@@ -0,0 +1,38 @@
+"""HyperStudy Python SDK — access experiment data from notebooks and scripts.
+
+Usage::
+
+    import hyperstudy
+
+    hs = hyperstudy.HyperStudy(api_key="hst_live_...")
+    events = hs.get_events("experiment_id")
+"""
+
+from ._types import DataType, RatingKind, Scope
+from .client import HyperStudy
+from .exceptions import (
+    AuthenticationError,
+    ForbiddenError,
+    HyperStudyError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HyperStudy",
+    "__version__",
+    # Exceptions
+    "HyperStudyError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ServerError",
+    "ValidationError",
+    # Enums
+    "Scope",
+    "DataType",
+    "RatingKind",
+]

hyperstudy-0.1.0/src/hyperstudy/_dataframe.py

@@ -0,0 +1,68 @@
+"""DataFrame conversion for API response data."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+
+def _post_process(df: pd.DataFrame) -> pd.DataFrame:
+    """Shared post-processing for pandas DataFrames.
+
+    * Parses timestamp columns to datetime.
+    * Computes ``onset_sec`` from ``onset`` (ms -> s).
+    """
+    if df.empty:
+        return df
+
+    # Parse common timestamp columns
+    for col in ("timestamp", "startTime", "endTime", "createdAt", "updatedAt"):
+        if col in df.columns:
+            df[col] = pd.to_datetime(df[col], errors="coerce")
+
+    # Compute onset in seconds
+    if "onset" in df.columns:
+        df["onset_sec"] = pd.to_numeric(df["onset"], errors="coerce") / 1000.0
+
+    return df
+
+
+def to_pandas(data: list[dict[str, Any]]) -> pd.DataFrame:
+    """Convert API response data to a pandas DataFrame with post-processing."""
+    if not data:
+        return pd.DataFrame()
+    df = pd.DataFrame(data)
+    return _post_process(df)
+
+
+def to_polars(data: list[dict[str, Any]]):
+    """Convert API response data to a polars DataFrame.
+
+    Raises ImportError with a helpful message if polars is not installed.
+    """
+    try:
+        import polars as pl
+    except ImportError:
+        raise ImportError(
+            "polars is not installed. Install it with: pip install hyperstudy[polars]"
+        ) from None
+
+    if not data:
+        return pl.DataFrame()
+
+    df = pl.DataFrame(data)
+
+    # Parse timestamps
+    for col in ("timestamp", "startTime", "endTime", "createdAt", "updatedAt"):
+        if col in df.columns:
+            try:
+                df = df.with_columns(pl.col(col).str.to_datetime(strict=False).alias(col))
+            except Exception:
+                pass  # Column may already be datetime or have unexpected format
+
+    # Compute onset_sec
+    if "onset" in df.columns:
+        df = df.with_columns((pl.col("onset").cast(pl.Float64) / 1000.0).alias("onset_sec"))
+
+    return df

hyperstudy-0.1.0/src/hyperstudy/_display.py

@@ -0,0 +1,64 @@
+"""Rich display helpers for Jupyter and marimo notebooks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ExperimentInfo:
+    """Wrapper around an experiment dict with ``_repr_html_`` for notebooks."""
+
+    def __init__(self, data: dict[str, Any]):
+        self._data = data
+
+    def __getitem__(self, key):
+        return self._data[key]
+
+    def __contains__(self, key):
+        return key in self._data
+
+    def get(self, key, default=None):
+        return self._data.get(key, default)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    def __repr__(self):
+        name = self._data.get("name", "Unknown")
+        eid = self._data.get("id", "?")
+        return f"Experiment({eid!r}, name={name!r})"
+
+    def _repr_html_(self) -> str:
+        d = self._data
+        rows = ""
+        display_fields = [
+            ("ID", "id"),
+            ("Name", "name"),
+            ("Description", "description"),
+            ("Owner", "ownerEmail"),
+            ("Rooms", "roomCount"),
+            ("Participants", "participantCount"),
+            ("Created", "createdAt"),
+            ("Updated", "updatedAt"),
+        ]
+        for label, key in display_fields:
+            val = d.get(key)
+            if val is not None:
+                rows += (
+                    f"<tr><th style='text-align:left;padding:4px 12px 4px 0'>"
+                    f"{label}</th><td style='padding:4px 0'>{val}</td></tr>"
+                )
+        return (
+            "<div style='font-family:system-ui,sans-serif;max-width:600px'>"
+            f"<h4 style='margin:0 0 8px'>Experiment: {d.get('name', '?')}</h4>"
+            f"<table style='border-collapse:collapse'>{rows}</table></div>"
+        )