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 tracker — Pupil Labs Neon, Ganzin Sol, or a webcam

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
"Ganzin"	Ganzin Sol
"Webcam"	Webcam tracking
"WT"	Default / mock tracker (for testing)

License entitlements

Your license enables specific models:

COGNITIVE_LOAD_MODEL

Enables Cognitive Load prediction.

FATIGUE_MODEL

Enables Fatigue prediction.

MENTAL_READINESS

Enables the Mental Readiness assessment.

ATTENTION

Enables Attention classification.

Getting help

Questions about the SDK, your license key, or a setup problem? Email support@harmoneyes.com and our team will get back to you.

To help us reproduce an issue, include your SDK version, Python version, operating system, and the eye tracker you are using.

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_fatigue_level()

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

get_mental_readiness(elapsed_seconds)

Get the Mental Readiness assessment, derived from accumulated Cognitive Load history. elapsed_seconds (float) — session elapsed time. Returns a dict with low_percentage, moderate_percentage and high_percentage (summing to 100.0), or None while the session is still too short.

get_attention()

Get the current Attention classification — attentional width on a 5-point scale. Returns a dict with level (int, 1 = narrow to 5 = broad) and label (for example “Narrow” or “Mod-Broad”), or None until at least 20 valid observations have accumulated.

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_fatigue_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

Bringing human-state intelligence to 8 billion devices.

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