cognitive3dpy 1.0.0__tar.gz

cognitive3dpy-1.0.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.3
+Name: cognitive3dpy
+Version: 1.0.0
+Summary: Python client for the Cognitive3D analytics API.
+Author: Mona
+Author-email: Mona <monajhzhu@gmail.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: polars>=1.38.1
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: pandas>=3.0 ; extra == 'pandas'
+Requires-Dist: pyarrow>=23.0.1 ; extra == 'pandas'
+Requires-Python: >=3.11
+Provides-Extra: pandas
+Description-Content-Type: text/markdown
+
+# cognitive3dpy
+
+`cognitive3dpy` is a Python client for the [Cognitive3D](https://cognitive3d.com) analytics API. It turns raw JSON responses into a Polars or Panadas DataFrames ready for analysis, handling authentication, pagination, property flattening, name resolution, and type coercion so you can go from API key to analysis-ready data in a few lines of code.
+
+## Installation
+
+```bash
+pip install cognitive3dpy
+```
+
+To enable pandas output (`output="pandas"`), install with the optional extra:
+
+```bash
+pip install "cognitive3dpy[pandas]"
+```
+
+## Getting an API Key
+
+1. Log in to your [Cognitive3D Dashboard](https://app.cognitive3d.com)
+2. Click your profile icon in the top-right corner and select **Settings**
+3. Navigate to the **API Keys** tab
+4. Click **Create API Key**, give it a name, and copy the generated key
+
+Store the key in a `.env` file (never commit this to version control):
+
+```bash
+C3D_API_KEY=your_api_key_here
+```
+
+Or set it as an environment variable in your shell:
+
+```bash
+export C3D_API_KEY=your_api_key_here
+```
+
+## Quick Start
+
+```python
+import cognitive3dpy as c3d
+
+# Authenticate and set project
+c3d.c3d_auth()        # reads C3D_API_KEY env var, or pass key directly
+c3d.c3d_project(4460) # set default project ID
+
+# Pull data
+sessions         = c3d.c3d_sessions(n=100)
+events           = c3d.c3d_events()
+results          = c3d.c3d_objective_results(group_by="steps")
+session_steps    = c3d.c3d_session_objectives()
+polls            = c3d.c3d_exitpoll()
+```
+
+## Data Streams
+
+| Function | Description | Key output columns |
+|---|---|---|
+| `c3d_sessions()` | Session-level metrics and properties | `session_id`, `duration_s`, `hmd`, `c3d_metrics_*`, `c3d_device_*`, `c3d_geo_*` |
+| `c3d_sessions(session_type="scene")` | Sessions split by scene visited — one row per session-scene | Adds `scene_id`, `scene_version_id`, `scene_name` |
+| `c3d_events()` | One row per in-session event with session context | `event_name`, `event_date`, `position_x/y/z`, `object`, `scene_name`, `prop_*` |
+| `c3d_objective_results()` | Objective success/failure counts by version | `objective_name`, `version_number`, `succeeded`, `failed`, `completion_rate` |
+| `c3d_objective_results(group_by="steps")` | Step-level detail for each objective | Adds `step_name`, `step_type`, `step_detail`, `avg_completion_time_s` |
+| `c3d_session_objectives()` | Per-session objective step results — one row per step per session | `session_id`, `participant_id`, `objective_name`, `step_number`, `step_description`, `step_result`, `step_duration_sec` |
+| `c3d_exitpoll()` | Exit poll survey responses | `question_title`, `value`, `value_label`, per hook/version |
+
+## Sessions
+
+Retrieve session-level data with optional date filtering and compact/full column modes.
+
+```python
+# Last 30 days, compact columns (default)
+sessions = c3d.c3d_sessions(n=100)
+
+# Custom date range, all columns
+sessions = c3d.c3d_sessions(
+    n=50,
+    start_date="2025-01-01",
+    end_date="2025-06-01",
+    compact=False,
+)
+```
+
+### Scene Sessions
+
+Use `session_type="scene"` to get session data broken out by scene — one row per session-scene combination. This is useful for comparing metrics across scenes within the same session. Defaults to the latest version of each scene.
+
+```python
+# All scenes, latest versions (default)
+scene_sessions = c3d.c3d_sessions(session_type="scene")
+
+# Filter to a specific scene
+scene_sessions = c3d.c3d_sessions(
+    session_type="scene",
+    scene_id="de704574-b03f-424e-be87-4985f85ed2e8",
+)
+
+# Filter to a specific scene version
+scene_sessions = c3d.c3d_sessions(
+    session_type="scene",
+    scene_version_id=7011,
+)
+```
+
+## Events
+
+Retrieve per-event data with session context attached. Events are unnested from sessions — one row per event. Dynamic object IDs are resolved to friendly names, and scene version IDs are resolved to scene names.
+
+```python
+events = c3d.c3d_events(
+    start_date="2025-01-01",
+    n=20,
+)
+```
+
+## Objective Results
+
+Query objective success/failure counts, optionally sliced by version or with step-level detail.
+
+```python
+# By version (default)
+results = c3d.c3d_objective_results(group_by="version")
+
+# Step-level detail
+detailed = c3d.c3d_objective_results(group_by="steps")
+```
+
+## Session Objectives
+
+Retrieve per-session objective step results. Returns one row per step per session, with step descriptions and outcomes.
+
+```python
+session_steps = c3d.c3d_session_objectives(
+    start_date="2025-01-01",
+    end_date="2025-06-01",
+)
+```
+
+## Exit Polls
+
+Retrieve exit poll response counts across all hooks and versions. Returns one row per response option per question per version, with human-readable value labels.
+
+```python
+# All hooks and versions
+polls = c3d.c3d_exitpoll()
+
+# Filter to a specific hook and version
+polls = c3d.c3d_exitpoll(hook="end_questions", version=3)
+```
+
+## Configuration
+
+### Timeout
+
+The default request timeout is 30 seconds per API call. To increase it:
+
+```python
+import cognitive3dpy as c3d
+
+c3d.c3d_set_timeout(60)  # 60 seconds
+```
+
+Or set the `C3D_TIMEOUT` environment variable before your session starts:
+
+```bash
+export C3D_TIMEOUT=60
+```
+
+`c3d_set_timeout()` takes effect immediately. The environment variable is read once on first import, so it must be set before importing the package.
+
+## Key Features
+
+- **Compact mode** — `c3d_sessions(compact=True)` (default) returns ~40 curated columns; `compact=False` returns everything
+- **Scene sessions** — `session_type="scene"` queries the latest version of each scene by default, giving the full project picture split by scene
+- **Automatic name resolution** — dynamic object SDK IDs are resolved to friendly names in events and objective steps; scene version IDs are resolved to scene names
+- **Date defaults** — all functions default to the last 30 days when no date range is specified
+- **Column naming** — top-level API fields use `snake_case`; Cognitive3D properties retain their `c3d_` prefix (e.g., `c3d_metrics_fps_score`)
+- **Polars-native** — returns `polars.DataFrame` by default; pass `output="pandas"` for a pandas DataFrame
+- **Session filtering** — `exclude_test`, `exclude_idle`, `min_duration` parameters across functions
+
+## Common Options
+
+All data-fetching functions support these session filters:
+
+- `exclude_test` / `exclude_idle` — filter out test and junk sessions (default `True`)
+- `start_date` / `end_date` — date range as a `date`/`datetime` object, epoch timestamp, or `"YYYY-MM-DD"` string
+- `min_duration` — minimum session duration in seconds
+- `project_id` — override the default set by `c3d_project()`
+- `output` — `"polars"` (default) or `"pandas"`
+- `warn_empty` — emit a `UserWarning` when 0 rows are returned (default `True`); set to `False` to suppress

cognitive3dpy-1.0.0/README.md

@@ -0,0 +1,188 @@
+# cognitive3dpy
+
+`cognitive3dpy` is a Python client for the [Cognitive3D](https://cognitive3d.com) analytics API. It turns raw JSON responses into a Polars or Panadas DataFrames ready for analysis, handling authentication, pagination, property flattening, name resolution, and type coercion so you can go from API key to analysis-ready data in a few lines of code.
+
+## Installation
+
+```bash
+pip install cognitive3dpy
+```
+
+To enable pandas output (`output="pandas"`), install with the optional extra:
+
+```bash
+pip install "cognitive3dpy[pandas]"
+```
+
+## Getting an API Key
+
+1. Log in to your [Cognitive3D Dashboard](https://app.cognitive3d.com)
+2. Click your profile icon in the top-right corner and select **Settings**
+3. Navigate to the **API Keys** tab
+4. Click **Create API Key**, give it a name, and copy the generated key
+
+Store the key in a `.env` file (never commit this to version control):
+
+```bash
+C3D_API_KEY=your_api_key_here
+```
+
+Or set it as an environment variable in your shell:
+
+```bash
+export C3D_API_KEY=your_api_key_here
+```
+
+## Quick Start
+
+```python
+import cognitive3dpy as c3d
+
+# Authenticate and set project
+c3d.c3d_auth()        # reads C3D_API_KEY env var, or pass key directly
+c3d.c3d_project(4460) # set default project ID
+
+# Pull data
+sessions         = c3d.c3d_sessions(n=100)
+events           = c3d.c3d_events()
+results          = c3d.c3d_objective_results(group_by="steps")
+session_steps    = c3d.c3d_session_objectives()
+polls            = c3d.c3d_exitpoll()
+```
+
+## Data Streams
+
+| Function | Description | Key output columns |
+|---|---|---|
+| `c3d_sessions()` | Session-level metrics and properties | `session_id`, `duration_s`, `hmd`, `c3d_metrics_*`, `c3d_device_*`, `c3d_geo_*` |
+| `c3d_sessions(session_type="scene")` | Sessions split by scene visited — one row per session-scene | Adds `scene_id`, `scene_version_id`, `scene_name` |
+| `c3d_events()` | One row per in-session event with session context | `event_name`, `event_date`, `position_x/y/z`, `object`, `scene_name`, `prop_*` |
+| `c3d_objective_results()` | Objective success/failure counts by version | `objective_name`, `version_number`, `succeeded`, `failed`, `completion_rate` |
+| `c3d_objective_results(group_by="steps")` | Step-level detail for each objective | Adds `step_name`, `step_type`, `step_detail`, `avg_completion_time_s` |
+| `c3d_session_objectives()` | Per-session objective step results — one row per step per session | `session_id`, `participant_id`, `objective_name`, `step_number`, `step_description`, `step_result`, `step_duration_sec` |
+| `c3d_exitpoll()` | Exit poll survey responses | `question_title`, `value`, `value_label`, per hook/version |
+
+## Sessions
+
+Retrieve session-level data with optional date filtering and compact/full column modes.
+
+```python
+# Last 30 days, compact columns (default)
+sessions = c3d.c3d_sessions(n=100)
+
+# Custom date range, all columns
+sessions = c3d.c3d_sessions(
+    n=50,
+    start_date="2025-01-01",
+    end_date="2025-06-01",
+    compact=False,
+)
+```
+
+### Scene Sessions
+
+Use `session_type="scene"` to get session data broken out by scene — one row per session-scene combination. This is useful for comparing metrics across scenes within the same session. Defaults to the latest version of each scene.
+
+```python
+# All scenes, latest versions (default)
+scene_sessions = c3d.c3d_sessions(session_type="scene")
+
+# Filter to a specific scene
+scene_sessions = c3d.c3d_sessions(
+    session_type="scene",
+    scene_id="de704574-b03f-424e-be87-4985f85ed2e8",
+)
+
+# Filter to a specific scene version
+scene_sessions = c3d.c3d_sessions(
+    session_type="scene",
+    scene_version_id=7011,
+)
+```
+
+## Events
+
+Retrieve per-event data with session context attached. Events are unnested from sessions — one row per event. Dynamic object IDs are resolved to friendly names, and scene version IDs are resolved to scene names.
+
+```python
+events = c3d.c3d_events(
+    start_date="2025-01-01",
+    n=20,
+)
+```
+
+## Objective Results
+
+Query objective success/failure counts, optionally sliced by version or with step-level detail.
+
+```python
+# By version (default)
+results = c3d.c3d_objective_results(group_by="version")
+
+# Step-level detail
+detailed = c3d.c3d_objective_results(group_by="steps")
+```
+
+## Session Objectives
+
+Retrieve per-session objective step results. Returns one row per step per session, with step descriptions and outcomes.
+
+```python
+session_steps = c3d.c3d_session_objectives(
+    start_date="2025-01-01",
+    end_date="2025-06-01",
+)
+```
+
+## Exit Polls
+
+Retrieve exit poll response counts across all hooks and versions. Returns one row per response option per question per version, with human-readable value labels.
+
+```python
+# All hooks and versions
+polls = c3d.c3d_exitpoll()
+
+# Filter to a specific hook and version
+polls = c3d.c3d_exitpoll(hook="end_questions", version=3)
+```
+
+## Configuration
+
+### Timeout
+
+The default request timeout is 30 seconds per API call. To increase it:
+
+```python
+import cognitive3dpy as c3d
+
+c3d.c3d_set_timeout(60)  # 60 seconds
+```
+
+Or set the `C3D_TIMEOUT` environment variable before your session starts:
+
+```bash
+export C3D_TIMEOUT=60
+```
+
+`c3d_set_timeout()` takes effect immediately. The environment variable is read once on first import, so it must be set before importing the package.
+
+## Key Features
+
+- **Compact mode** — `c3d_sessions(compact=True)` (default) returns ~40 curated columns; `compact=False` returns everything
+- **Scene sessions** — `session_type="scene"` queries the latest version of each scene by default, giving the full project picture split by scene
+- **Automatic name resolution** — dynamic object SDK IDs are resolved to friendly names in events and objective steps; scene version IDs are resolved to scene names
+- **Date defaults** — all functions default to the last 30 days when no date range is specified
+- **Column naming** — top-level API fields use `snake_case`; Cognitive3D properties retain their `c3d_` prefix (e.g., `c3d_metrics_fps_score`)
+- **Polars-native** — returns `polars.DataFrame` by default; pass `output="pandas"` for a pandas DataFrame
+- **Session filtering** — `exclude_test`, `exclude_idle`, `min_duration` parameters across functions
+
+## Common Options
+
+All data-fetching functions support these session filters:
+
+- `exclude_test` / `exclude_idle` — filter out test and junk sessions (default `True`)
+- `start_date` / `end_date` — date range as a `date`/`datetime` object, epoch timestamp, or `"YYYY-MM-DD"` string
+- `min_duration` — minimum session duration in seconds
+- `project_id` — override the default set by `c3d_project()`
+- `output` — `"polars"` (default) or `"pandas"`
+- `warn_empty` — emit a `UserWarning` when 0 rows are returned (default `True`); set to `False` to suppress

cognitive3dpy-1.0.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "cognitive3dpy"
+version = "1.0.0"
+description = "Python client for the Cognitive3D analytics API."
+readme = "README.md"
+authors = [
+    { name = "Mona", email = "monajhzhu@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28.1",
+    "polars>=1.38.1",
+    "python-dateutil>=2.9.0.post0",
+]
+
+[project.optional-dependencies]
+pandas = [
+    "pandas>=3.0",
+    "pyarrow>=23.0.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.6,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.2.0",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "python-semantic-release>=9.0.0",
+    "respx>=0.22.0",
+    "ruff>=0.15.2",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+branch = "main"
+commit_message = "chore(release): v{version} [skip ci]"
+
+[tool.semantic_release.changelog]
+exclude_commit_patterns = ["^chore"]

cognitive3dpy-1.0.0/src/cognitive3dpy/__init__.py

@@ -0,0 +1,38 @@
+"""cognitive3dpy — Python client for the Cognitive3D Analytics REST API."""
+
+from importlib.metadata import version
+
+__version__ = version("cognitive3dpy")
+
+from cognitive3dpy._client import (
+    C3DAPIError,
+    C3DAuthError,
+    C3DError,
+    C3DNotFoundError,
+    c3d_set_timeout,
+)
+from cognitive3dpy.auth import c3d_auth, c3d_project
+from cognitive3dpy.events import c3d_events
+from cognitive3dpy.exitpoll import c3d_exitpoll
+from cognitive3dpy.objectives import c3d_objective_results
+from cognitive3dpy.session_objectives import c3d_session_objectives
+from cognitive3dpy.sessions import c3d_sessions
+
+__all__ = [
+    # Auth
+    "c3d_auth",
+    "c3d_project",
+    # Data functions
+    "c3d_sessions",
+    "c3d_events",
+    "c3d_objective_results",
+    "c3d_session_objectives",
+    "c3d_exitpoll",
+    # Config
+    "c3d_set_timeout",
+    # Exceptions
+    "C3DError",
+    "C3DAuthError",
+    "C3DNotFoundError",
+    "C3DAPIError",
+]

cognitive3dpy-1.0.0/src/cognitive3dpy/_client.py

@@ -0,0 +1,139 @@
+"""HTTP client wrapper for the Cognitive3D API."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import time
+
+import httpx
+
+from cognitive3dpy.auth import get_api_key
+
+logger = logging.getLogger(__name__)
+
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+_MAX_RETRIES = 3
+_BACKOFF_BASE = 1.0  # seconds
+
+BASE_URL = "https://api.cognitive3d.com"
+_DEFAULT_TIMEOUT = 30.0
+
+_client: httpx.Client | None = None
+_timeout: float = float(os.environ.get("C3D_TIMEOUT", _DEFAULT_TIMEOUT))
+
+
+def _close_client() -> None:
+    if _client is not None and not _client.is_closed:
+        _client.close()
+
+
+atexit.register(_close_client)
+
+
+class C3DError(Exception):
+    """Base exception for Cognitive3D API errors."""
+
+
+class C3DAuthError(C3DError):
+    """Raised on 401 Unauthorized."""
+
+
+class C3DNotFoundError(C3DError):
+    """Raised on 404 Not Found."""
+
+
+class C3DAPIError(C3DError):
+    """Raised on any other non-2xx response."""
+
+
+def _get_client() -> httpx.Client:
+    """Return a reusable httpx client, creating one if needed."""
+    global _client
+    if _client is None or _client.is_closed:
+        _client = httpx.Client(base_url=BASE_URL, timeout=_timeout)
+    return _client
+
+
+def c3d_set_timeout(seconds: float) -> None:
+    """Set the HTTP request timeout for all API calls.
+
+    Takes effect immediately by recreating the underlying HTTP client.
+    Can also be configured via the ``C3D_TIMEOUT`` environment variable
+    before the first API call.
+
+    Parameters
+    ----------
+    seconds : float
+        Timeout in seconds per request. Default is 30.0.
+    """
+    global _timeout, _client
+    _timeout = float(seconds)
+    if _client is not None and not _client.is_closed:
+        _client.close()
+    _client = None
+
+
+def _build_headers() -> dict[str, str]:
+    """Build request headers with the stored API key."""
+    return {
+        "Authorization": get_api_key(),
+        "Content-Type": "application/json",
+    }
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Raise a typed exception for non-2xx responses."""
+    if response.is_success:
+        return
+    msg = f"{response.status_code}: {response.text}"
+    if response.status_code == 401:
+        raise C3DAuthError(msg)
+    if response.status_code == 404:
+        raise C3DNotFoundError(msg)
+    raise C3DAPIError(msg)
+
+
+def _execute_with_retry(fn) -> httpx.Response:
+    """Execute a request callable with exponential backoff on transient errors."""
+    last_exc: Exception | None = None
+    for attempt in range(_MAX_RETRIES):
+        try:
+            response = fn()
+            if response.status_code not in _RETRYABLE_STATUS:
+                return response
+            last_exc = C3DAPIError(f"{response.status_code}: {response.text}")
+        except httpx.TransportError as exc:
+            last_exc = exc
+
+        wait = _BACKOFF_BASE * (2**attempt)
+        logger.warning(
+            "Request failed (attempt %d/%d), retrying in %.1fs...",
+            attempt + 1,
+            _MAX_RETRIES,
+            wait,
+        )
+        time.sleep(wait)
+
+    raise last_exc
+
+
+def c3d_request(endpoint: str, body: dict) -> dict | list:
+    """POST to the API and return the parsed JSON response."""
+    client = _get_client()
+    response = _execute_with_retry(
+        lambda: client.post(endpoint, headers=_build_headers(), json=body)
+    )
+    _raise_for_status(response)
+    return response.json()
+
+
+def c3d_get(endpoint: str) -> dict | list:
+    """GET from the API and return the parsed JSON response."""
+    client = _get_client()
+    response = _execute_with_retry(
+        lambda: client.get(endpoint, headers=_build_headers())
+    )
+    _raise_for_status(response)
+    return response.json()