Platform Science & Research Pricing Developers Company

Python SDK

Stream or batch-process eye movement into real-time human-state intelligence. Ideal for pipelines, research, and ML/AI workflows. Requires Python 3.12 and a Theia license key.

Install Getting started API reference

Install

Install the Python SDK

Requirements

Python 3.12
pip (Python package installer)
A supported eye-tracking device (Pupil Labs Neon)

Installation

Install the TheiaSDK Python package using pip:

pip install git+https://github.com/harmoneyes/HarmonEyesTheia.git

Getting started

Set up and authorize

License key setup

TheiaSDK requires a valid license key. Contact us to obtain a license.

Supported platforms

Platform	Description
"PL"	Pupil Labs Neon
"WT"	Default / mock tracker (for testing)

License entitlements

Your license enables specific models:

COGNITIVE_LOAD_MODEL

Enables Cognitive Load prediction.

DROWSINESS_MODEL

Enables Fatigue prediction.

In the SDK, the Cognitive Load capability is exposed under cog_load identifiers and Fatigue under drowsiness.

API reference

TheiaSDK class

Constructor

harmoneyes_theia.TheiaSDK(
    license_key,
    platform="PL",
)

Parameter	Type	Default	Description
license_key	str	Required	Your SDK license key
platform	str	"PL"	Eye tracking platform ("PL", "WT")

Streaming methods

start_new_session(session_uuid, task_type)

Start a new data-collection session. session_uuid (str) — unique session identifier; task_type (str) — task type for labeling.

stop_processing()

Stop data collection and clean up resources.

start_realtime_video()

Start video streaming from the eye tracker.

start_realtime_data()

Start eye-tracking data collection and processing.

get_cog_load_levels()

Get the current Cognitive Load prediction. Returns a tuple (levels_dict, batch_number) — levels_dict holds value (0 = low, 1 = moderate, 2 = high), label, and confidence.

get_drowsiness_level()

Get the current Fatigue prediction. Updates every ~120 seconds. Returns (drowsiness_dict, batch_number) — value (0–3), label, confidence.

get_video_frame()

Get the current video frame from the eye tracker. Returns a video frame, or None if unavailable.

has_connection_timeout()

Check if the device connection has timed out. Returns bool.

is_video_streaming()

Check if video is actively streaming. Returns bool.

Batch processing methods

predict_cog_load_batch(data, n_jobs=1)

Process raw eye-tracking data and predict Cognitive Load for each second. data (str/Path/DataFrame) — raw CSV path or DataFrame; n_jobs (int) — CPU cores (default 1, -1 for all). Returns a list of dicts with keys timestamp (float), value (0/1/2), label ("Low"/"Moderate"/"High"), confidence (0.0–1.0).

predict_drowsiness_batch(data, timezone=None, prediction_stride=120, n_jobs=1)

Process raw eye-tracking data and predict Fatigue using 120-second windows. timezone (ZoneInfo) — for time-of-day encoding; prediction_stride (int) — predict every N seconds (default 120). Returns a list of dicts: timestamp, value (0 = alert … 3 = drowsy), label ("Alert", "Neither Alert Nor Drowsy", "Rather Drowsy", "Drowsy"), confidence.

refine_cog_load_batch(data, refining_data, n_jobs=1)

Refine the Cognitive Load model with ground-truth labeled data. refining_data (list) — 3-tuples (start_unix_timestamp, end_unix_timestamp, "Low" | "High"). Returns bool (True if refining succeeded).

Model management

reset_models_batch()

Reset SDK models to their initial state. Use when processing independent recordings.

save_refined_model()

Manually save the refined Cognitive Load model to disk. Returns bool.

reset_to_base_model()

Delete the refined model and reload the base model. Returns bool.

get_model_info()

Get information about the current Cognitive Load model. Returns a dict: refinement_count, total_training_samples, is_refined.

Error handling

The SDK raises specific exceptions for error conditions:

LicenseValidationError: invalid license key format or tampered license
LicenseExpiredError: license has expired
LicenseNetworkError: network issues when validating the license
LicenseFeatureNotEntitledError: feature not enabled in the license

from harmoneyes_theia import (
    LicenseValidationError,
    LicenseExpiredError,
    LicenseFeatureNotEntitledError,
)

try:
    sdk = harmoneyes_theia.TheiaSDK(
        license_key="your-license-key",
        platform="PL",
    )
except LicenseValidationError as e:
    print(f"License validation failed: {e}")
except LicenseExpiredError as e:
    print(f"License expired: {e}")

Start building today.

Free developer tier, full SDK access, no credit card to start.

Get started Back to Developers

The foundation model for human-state intelligence, measured from eye movement alone.

Product

Platform Pricing Developers

Developers

Get started Python SDK Unity SDK Theia Dashboard

Company

About Science & Research Contact

HarmonEyes technology is patented. Privacy statement: the HarmonEyes service does not record, collect or store any personal user data or eye-tracking data. Bethesda, Maryland, USA · sales@harmoneyes.com