API Reference

TheiaSDK Class

Constructor

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

Parameters:

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

Streaming Methods

Session Management

cstart_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 cleanup resources.

Data Collection

start_realtime_video()

Start video streaming from the eye tracker.

start_realtime_data()

Start eye tracking data collection and processing.

Predictions

get_cog_load_levels()

Get the current cognitive load prediction.
Returns: Tuple of (levels_dict, batch_number)

• levels_dict – Dict with value (0=low, 1=moderate, 2=high), label, confidence
• batch_number – Current batch number

get_drowsiness_level()

Get the current drowsiness prediction. Updates every ~120 seconds.
Returns: Tuple of (drowsiness_dict, batch_number)

• drowsiness_dict – Dict with value (0-3), label, confidence
• batch_number – Current batch number

get_video_frame()

Get the current video frame from the eye tracker.
Returns: Video frame or None if not available

Status

has_connection_timeout()

Check if 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.

Parameters:

• data (str/Path/DataFrame) – Raw eye tracking CSV file path or DataFrame
• n_jobs (int) – Number of CPU cores (default 1, -1 for all cores)

Returns: List of dicts with keys:

• timestamp – float, seconds from start
• value – int (0=low, 1=moderate, 2=high)
• label – str (“Low”, “Moderate”, “High”)
• confidence – float (0.0-1.0)

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

Process raw eye tracking data and predict drowsiness using 120-second windows.

Parameters:

• data (str/Path/DataFrame) – Raw eye tracking CSV file path or DataFrame
• timezone (ZoneInfo) – Timezone for time-of-day encoding
• prediction_stride (int) – Predict every N seconds (default 120)
• n_jobs (int) – Number of CPU cores (default 1, -1 for all cores)

Returns: List of dicts with keys:

• timestamp – float, seconds from start
• value – int (0=alert, 1, 2, 3=drowsy)
• label – str (“Alert”, “Neither Alert Nor Drowsy”, “Rather Drowsy”, “Drowsy”)
• confidence – float (0.0-1.0)

refine_cog_load_batch(data, refining_data, n_jobs=1)

Refine the cognitive load model with ground truth labeled data.

Parameters:

• data (str/Path/DataFrame) – Raw eye tracking CSV file path or DataFrame
• refining_data (list) – List of 3-tuples: (start_unix_timestamp, end_unix_timestamp, “Low”|”High”)
• n_jobs (int) – Number of CPU cores

Returns: bool (True if refining succeeded)

Model Management

reset_models_batch()

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

save_refined_model()

Manually save the refined cognitive load model to disk.

Returns: bool (True if save succeeded)

reset_to_base_model()

Delete refined model and reload base model.

Returns: bool (True if reset succeeded)

get_model_info()

Get information about the current cognitive load model.

Returns: dict with keys:

• refinement_count – Number of refinements applied
• total_training_samples – Total training samples used
• is_refined – Whether a refined model is loaded

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 license
• LicenseFeatureNotEntitledError – Feature not enabled in 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}")