NeuraDock Visual Cognitive Load Agent Tutorial: A Quality-Gated Open-Source EEG Workflow for Alpha Dynamics and Real-Time Applications

# NeuraDock Visual Cognitive Load Agent Tutorial: A Quality-Gated Open-Source EEG Workflow for Alpha Dynamics and Real-Time Applications
Source: [https://arxiv.org/html/2606.26518](https://arxiv.org/html/2606.26518)
Zhiyuan Xu, Yueqing Dai, Junling Li and Junwen Luo Shanghai Pulse Element Intelligent Technology Co\., Ltd\. \(NeuraDock\)

\(Tutorial manuscript, updated for release 2026\.06\.24\)

###### Abstract

This tutorial paper provides a step\-by\-step, reproducible walkthrough of NeuraDock Agent, an open\-source EEG agent focused on Alpha dynamics and visual cognitive\-load analysis\. The goal is practical: a reader should be able to install the agent, run EEG preprocessing and quality control, generate Alpha dynamics figures, perform within\-subject Rest/Task visual cognitive\-load comparison, run the public mini\-dataset analyses and compare them with the reference validation summary, start an online dashboard, call the real\-time API from an external application, and use the LLM interpretation layer to explain quality risks\. Existing EEG toolkits provide excellent offline analysis, but assembling a real\-time, quality\-gated cognitive\-load pipeline often requires manually bridging acquisition, custom QC, Alpha feature extraction, and a web API; this tutorial closes that offline\-to\-online gap\. The tutorial uses a quality\-gated workflow: downstream Alpha and workload metrics are computed only after preprocessing and QC gating rather than directly from raw EEG\. In the included mini\-dataset validation, the agent processed 18 recordings, generated 10 within\-subject comparisons, observed task\-related posterior Alpha suppression in 7 of 10 contrasts, estimated initial evidence of within\-subject repeatability, and benchmarked local online API latency\. The tutorial is intended for researchers, developers, and applied teams who want a transparent path from EEG files to real\-time visual cognitive\-load prototypes\.

Keywords:EEG tutorial; visual cognitive load; Alpha dynamics; posterior Alpha suppression; open source; real\-time API; quality control; NeuraDock Agent

## 1Reader Goal

This tutorial is written as a hands\-on paper\. By the end, a reader should be able to reproduce the following outputs:

- •EEG preprocessing and signal\-quality reports\.
- •Clean/QC\-gated EEG output files\.
- •Alpha dynamics time\-domain, frequency\-domain, and time\-frequency figures\.
- •Within\-subject offline Rest/Task cognitive\-load comparison figures\.
- •Mini\-dataset per\-recording and within\-subject comparison outputs\.
- •A real\-time local dashboard and API endpoint\.
- •LLM\-based explanations of computed EEG results and quality risks\.

More importantly, by the end of the tutorial the reader will have a local HTTP endpoint that streams a visual workload index and quality flag to an application\. Wiring together that path from offline EEG scripts to a live API is often the part that turns a promising cognitive\-load idea into weeks of infrastructure work\.

The tutorial also states what the workflow is not: it is not a clinical diagnostic system, not an attention or fatigue diagnosis, and not a cross\-subject cognitive\-ability ranking method\.

## 2Why a Tutorial Workflow Is Needed

General EEG tools such as MNE\-Python, EEGLAB, and BrainFlow are powerful and open source, but they are broad toolkits rather than focused cognitive\-load workflows\[[1](https://arxiv.org/html/2606.26518#bib.bib1),[2](https://arxiv.org/html/2606.26518#bib.bib2),[4](https://arxiv.org/html/2606.26518#bib.bib4),[5](https://arxiv.org/html/2606.26518#bib.bib5),[3](https://arxiv.org/html/2606.26518#bib.bib3)\]\. Commercial and device\-specific systems such as Emotiv Cortex and Neurosity SDK workflows provide real\-time data access, but they are not fully open, locally auditable cognitive\-load analysis stacks\[[6](https://arxiv.org/html/2606.26518#bib.bib6),[7](https://arxiv.org/html/2606.26518#bib.bib7)\]\. Existing cognitive\-load studies often remain offline and do not provide a complete path from preprocessing to a real\-time API\. This creates the practical “why now” gap: teams building adaptive interfaces, XR demos, HMI experiments, or internal workload dashboards can analyze EEG offline, but still struggle to deploy the same logic as a quality\-gated service that another application can call once per second\.

NeuraDock Agent fills this gap by packaging a focused tutorial workflow:

Install

\-\>Checkprofile

\-\>Preprocessandquality\-gateEEG

\-\>AnalyzeAlphadynamics

\-\>CompareRest/Taskwithinsubject

\-\>Runpublicmini\-datasetanalyses

\-\>Startonlinedashboard/API

\-\>InterpretresultswithLLMsummarylayer

The value is not only a feature extractor\. The value is an auditable, repeatable route from EEG data to cognitive\-load application prototypes\.

## 3Tutorial Assumptions

The commands below assume Windows PowerShell and that the current directory is the root of the clonedeeg\-workstation\-agentrepository\. All paths are relative to that repository; no machine\-specific installation path is required\.

The short examples use public files downloaded and SHA256\-verified by the repository’s data helper:

data\_examples\\alpha\\open\_closed\_eye2\.txt

data\_examples\\rest\_task\\rest\_S01\_1\.txt

data\_examples\\rest\_task\\task\_S01\_1\.txt

The workflow uses a seven\-channel NeuraDock profile and a 250 Hz sampling rate\. The posterior and parieto\-occipital channels are used for visual Alpha features\.

## 4Step 1: Install and Check the Agent

Clone the open\-source repository and enter its root directory:

gitclonehttps://github\.com/Neuradock/eeg\-workstation\-agent\.git

cdeeg\-workstation\-agent

Create a virtual environment and install the agent:

py\-mvenv\.venv

\.\\\.venv\\Scripts\\python\.exe\-mpipinstall\-\-upgradepip

\.\\\.venv\\Scripts\\python\.exe\-mpipinstall\-e"\.\[dev\]"

Download the three public example recordings used in Steps 2–4:

\.\\\.venv\\Scripts\\python\.exescripts\\download\_example\_data\.py

The downloader verifies each file against a release\-pinned SHA256 value\. Human EEG recordings are maintained in the separate data repository; the MIT software license does not automatically replace the data repository’s usage and redistribution terms\.

Check the version and hardware profile:

\.\\\.venv\\Scripts\\neuradock\-agent\.exe\-\-version

\.\\\.venv\\Scripts\\neuradock\-agent\.exeprofile

Expected version:

The actual hardware profile output from this tutorial run was:

\{

"profile\_version":"1\.1",

"device":"NeuraDockEEGWorkstation",

"hardware\_revision":"public\-profile\-v2",

"sampling\_rate\_hz":250,

"channels":\["CP5","CP6","PO3","PO4","O1","Oz","O2"\],

"amplitude\_unit":"microvolts",

"line\_frequency\_hz":50\.0,

"tcp\_default\_ip":"127\.0\.0\.1",

"tcp\_default\_port":9600,

"tcp\_start\_command":"start",

"packet\_total\_channels":8,

"packet\_used\_channels":7,

"bluetooth\_samples\_per\_packet":5,

"quality":\{

"line\_noise\_power":10\.0,

"emg\_power":20\.0,

"outlier\_count\_per\_second":2,

"outlier\_absolute\_amplitude":100\.0,

"bad\_channel\_segment\_ratio":0\.4,

"minimum\_neighbor\_correlation":0\.15

\},

"channel\_count":7

\}

This confirms that the tutorial uses a 7\-channel profile sampled at 250 Hz, with posterior channelsPO3,PO4,O1,Oz, andO2available for visual Alpha features\. The TCP defaults also explain why online mode can start from only an IP address and port\.

### 4\.1Hardware\-Tuned Design

The NeuraDock montage is not arbitrary for this tutorial\. The posterior ringPO3/PO4/O1/Oz/O2targets occipital and parieto\-occipital Alpha dynamics, which are the primary signal family used here for visual cognitive\-load estimation\. The lateral channelsCP5/CP6provide additional spatial context for quality checks and posterior asymmetry interpretation\. The agent can ingest generic 7\-channel data with the same shape, but the spatial QC thresholds, posterior\-channel grouping, and right\-minus\-left asymmetry metrics are calibrated for this NeuraDock geometry\. For best results, use the NeuraDock hardware profile rather than treating the agent as an arbitrary EEG file parser\.

## 5Step 2: Run EEG Preprocessing and Quality Control

Preprocessing is the first scientific checkpoint\. Run:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze‘

data\_examples\\alpha\\open\_closed\_eye2\.txt‘

\-\-workflowquality

Typical output structure:

runs/<timestamp\>\_quality/

\|\-\-report\.md

\|\-\-results\.json

\|\-\-clean\_eeg\_data\.npz

‘\-\-figures/

\|\-\-signal\_quality\.png

‘\-\-clean\_signal\.png

How to read this step:

- •report\.mdis the human\-readable QC report\.
- •results\.jsoncontains retention rate, warning messages, rejected segment information, and bad\-channel candidates\.
- •clean\_eeg\_data\.npzstores the clean/QC\-gated EEG data\.
- •The figures help inspect retained signal quality and rejected portions\.

The actual tutorial run onopen\_closed\_eye2\.txtproduced:

Summary:signal\_quality:retained65\.9%,status=warning

raw\_shape:\[7,13210\]

clean\_shape:\[7,8710\]

retention\_rate:0\.659

rejected\_segment\_count:18

bad\_channel\_candidates:\[\]

warnings:

\-Only65\.9%ofsamplespassedsegmentQC\.

\-Bodyactivityheuristic:slight\_activity\_or\_mild\_muscle\_tension\.

The result is usable for tutorial purposes, but it is not a perfectly clean recording\. The agent explicitly marks the run aswarningbecause roughly one third of samples were rejected by segment\-level QC\. This is the desired behavior: downstream Alpha analysis should inherit this caution rather than pretending the signal was clean\.

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_open_closed_eye2_signal_quality.png)Figure 1:Signal\-quality figure from the actualopen\_closed\_eye2\.txtpreprocessing run\. The report retained 65\.9% of samples and flagged mild body activity or muscle tension\.![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_open_closed_eye2_clean_signal.png)Figure 2:Clean EEG signal after preprocessing and QC gating foropen\_closed\_eye2\.txt\. Later tutorial metrics are based on this quality\-gated workflow rather than raw EEG alone\.This is a core design principle: later Alpha and workload metrics are based on the preprocessed/QC\-gated workflow, not directly on raw EEG\.

## 6Step 3: Analyze Alpha Dynamics

Run the Alpha dynamics workflow:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze‘

data\_examples\\alpha\\open\_closed\_eye2\.txt‘

\-\-workflowalphadynamics

Typical output structure:

runs/<timestamp\>\_alpha\_dynamics/

\|\-\-report\.md

\|\-\-results\.json

‘\-\-figures/

\|\-\-alpha\_time\_domain\.png

\|\-\-alpha\_frequency\_domain\.png

‘\-\-alpha\_time\_frequency\.png

The Alpha dynamics workflow automatically identifies weak Alpha, baseline Alpha, strong Alpha, Alpha suppression from baseline, peak Alpha frequency, and right\-minus\-left Alpha asymmetry\. The actualopen\_closed\_eye2\.txtrun produced:

Summary:alpha\_dynamics:weak=4,strong=4,maxsuppression=\+0\.731

quality\_status:warning

retention\_rate:0\.659

valid\_window\_count:10

excluded\_window\_count:39

weak\_alpha/baseline\_alpha/strong:4/2/4

max\_alpha\_suppression\_from\_baseline:0\.731

median\_alpha\_peak\_hz:10\.25

median\_alpha\_asymmetry\_right\_minus\_left:0\.309

warnings:

\-Only65\.9%ofsamplespassedsegmentQC\.

\-39Alphawindowswereexcludedbecausecleanretentionwasbelow80%\.

This output is intentionally conservative\. Only 10 Alpha windows were quality\-valid, so the Alpha dynamics are useful as a demonstration of the feature pipeline but should be interpreted with the QC warning in mind\.

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_open_closed_eye2_alpha_time_frequency.png)Figure 3:Actualopen\_closed\_eye2\.txtAlpha dynamics time\-frequency output\. This replaces the earlier task\-recording example and matches the command in this tutorial step\.![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_open_closed_eye2_alpha_time_domain.png)

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_open_closed_eye2_alpha_frequency_domain.png)

Figure 4:Time\-domain and frequency\-domain Alpha dynamics figures generated from the sameopen\_closed\_eye2\.txtrun\.
## 7Step 4: Run Offline Rest/Task Visual Cognitive\-Load Comparison

For offline workload comparison, always compare a subject to their own baseline\. Use the Rest file first and Task file second:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze‘

data\_examples\\rest\_task\\rest\_S01\_1\.txt‘

data\_examples\\rest\_task\\task\_S01\_1\.txt‘

\-\-workflowvisualcognitioncomparison

With explicit labels:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze‘

data\_examples\\rest\_task\\rest\_S01\_1\.txt‘

data\_examples\\rest\_task\\task\_S01\_1\.txt‘

\-\-workflowvisualcognitioncomparison‘

\-\-condition\-labelsRestTask

Typical output structure:

runs/<timestamp\>\_visual\_cognitive\_load\_comparison/

\|\-\-report\.md

\|\-\-results\.json

‘\-\-figures/

\|\-\-visual\_cognitive\_load\_comparison\.png

\|\-\-rest\_visual\_cognitive\_load\.png

‘\-\-task\_visual\_cognitive\_load\.png

Interpretation rule:

TaskminusRestposteriorlogAlpha<0

\-\>TaskhaslowerposteriorAlphathanRest

\-\>Thisisconsistentwithtask\-relatedAlphasuppression

This comparison is descriptive and within\-subject\. It should not be used to compare one subject’s cognitive ability against another subject\.

The actual tutorial run forrest\_S01\_1\.txtversustask\_S01\_1\.txtproduced:

Summary:visual\_cognitive\_load\_comparison:

Task\-RestmedianlogAlpha=\-0\.024

RestmedianposteriorlogAlpha:1\.141

TaskmedianposteriorlogAlpha:1\.117

TaskminusRest:\-0\.024

Task/RestAlphapowerratio:0\.946

RestmedianAlphapeak:11\.00Hz

TaskmedianAlphapeak:11\.25Hz

Peakshift:\+0\.25Hz

Restretention:93\.3%

Taskretention:78\.9%

Taskquality:warning

The direction of the primary contrast is consistent with mild task\-related posterior Alpha suppression: Task Alpha was lower than Rest Alpha\. However, the effect is small and the Task condition had a quality warning, so the correct interpretation is cautious: this is a descriptive within\-subject contrast, not proof of higher cognitive load\.

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_rest_task_comparison.png)Figure 5:Actual Rest/Task comparison figure fromrest\_S01\_1\.txtandtask\_S01\_1\.txt\. The primary contrast is the median posterior log Alpha difference between Task and Rest\.![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_rest_visual_cognitive_load.png)

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_task_visual_cognitive_load.png)

Figure 6:Condition\-level visual cognitive\-load plots for the Rest and Task recordings\. Blank or disconnected regions correspond to QC\-excluded windows, not zero workload\.
## 8Step 5: Run the Public Mini\-Dataset Analyses

The complete human EEG mini\-dataset is versioned in the separate public data repository\. Clone that branch next to the agent repository:

gitclone\-\-branchadd\-visual\-cognitive\-load\-mini\-dataset\-20260622‘

\-\-single\-branch‘

https://github\.com/Neuradock/eeg\-workstation\-data\.git‘

\.\.\\eeg\-workstation\-data

Define a relative data root from the agent repository:

$dataRoot="\.\.\\eeg\-workstation\-data\\visual\_cognitive\_load\\mini\_dataset\_v20260622"

Run Alpha Dynamics on all 18 recordings using the public CLI:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze$dataRoot‘

\-\-recursive‘

\-\-workflowalphadynamics‘

\-\-output\-rootruns\\mini\_dataset\_alpha

The following reusable PowerShell function runs a quality\-gated, within\-subject comparison:

functionCompare\-NeuraDockPair\{

param\($Reference,$Comparison,$ReferenceLabel,$ComparisonLabel\)

\.\\\.venv\\Scripts\\neuradock\-agent\.exeanalyze‘

$Reference$Comparison‘

\-\-workflowvisualcognitioncomparison‘

\-\-condition\-labels$ReferenceLabel$ComparisonLabel‘

\-\-output\-rootruns\\mini\_dataset\_comparisons

\}

Run the six Rest/Task session comparisons:

foreach\($subjectin"S01","S02","S03"\)\{

foreach\($sessionin1,2\)\{

$folder="$dataRoot\\cohort\_3subj\_rest\_task\\$subject"

Compare\-NeuraDockPair‘

"$folder\\rest\_$\{subject\}\_$\{session\}\.txt"‘

"$folder\\task\_$\{subject\}\_$\{session\}\.txt"‘

"Rest""Task"

\}

\}

Run the four task\-variant comparisons:

$cohort="$dataRoot\\cohort\_2subj\_ljw\_xzy"

Compare\-NeuraDockPair"$cohort\\ljw\\01\_rest\.txt"‘

"$cohort\\ljw\\02\_chat\.txt""Rest""Chat"

Compare\-NeuraDockPair"$cohort\\ljw\\01\_rest\.txt"‘

"$cohort\\ljw\\03\_game\.txt""Rest""Game"

Compare\-NeuraDockPair"$cohort\\xzy\\01\_rest\_eye\_half\.txt"‘

"$cohort\\xzy\\02\_music\_eye\_half\.txt""Rest""Music"

Compare\-NeuraDockPair"$cohort\\xzy\\01\_rest\_eye\_half\.txt"‘

"$cohort\\xzy\\03\_game\.txt""Rest""Game"

Each command writes a timestamped run containingreport\.md,results\.json, and quality\-gated figures\. The aggregate figures below were assembled from those public per\-recording and per\-comparison outputs during the reference validation\. They are shown as a compact article summary; the supported public CLI contract is the individual analysis output described above\.

The validation policy is intentionally conservative:

- •No cross\-subject comparisons are made\.
- •Each task is compared only to the same subject’s own rest or baseline file\.
- •Mixed\-eye recordings are retained as caveats rather than silently treated as clean protocol data\.
- •All reported Alpha and workload metrics are computed after preprocessing and QC gating\.

![Refer to caption](https://arxiv.org/html/2606.26518v1/mini_dataset_professional_summary.png)Figure 7:Reference mini\-dataset summary assembled from the public quality\-gated analysis outputs\.![Refer to caption](https://arxiv.org/html/2606.26518v1/mini_dataset_alpha_overview.png)Figure 8:Reference Alpha dynamics overview across the mini\-dataset\. Each row is one recording after preprocessing and QC gating\.![Refer to caption](https://arxiv.org/html/2606.26518v1/mini_dataset_comparison_overview.png)Figure 9:Reference within\-subject comparison overview\. Negative task\-minus\-rest log Alpha indicates stronger task\-related Alpha suppression\.### 8\.1Mini\-Dataset Results to Check

The reference run analyzed 18 recordings and generated 10 within\-subject comparisons\. Seven of 10 contrasts showed lower task posterior Alpha than rest\. In the most interpretable cases, task\-related posterior Alpha suppression reached approximately 50% power reduction, consistent with the expected direction from visual\-load Alpha literature\. The clearest examples were:

- •xzy Game vs Rest: Task minus Rest log Alpha = \-0\.303, Task/Rest Alpha ratio = 0\.50\.
- •ljw Chat vs Rest: Task minus Rest log Alpha = \-0\.283, Task/Rest Alpha ratio = 0\.52\.
- •ljw Game vs Rest: Task minus Rest log Alpha = \-0\.112, Task/Rest Alpha ratio = 0\.77\.

Thexzy Music vs Restcontrast moved in the opposite direction and should be interpreted cautiously because of the mixed\-eye caveat\. This is a useful tutorial outcome: a credible tool should reveal risk cases and unexpected directions rather than force every task into a high\-load result\.

Baseline retest analysis forS01\-\-S03Rest session 1 versus Rest session 2 showed Pearsonr=0\.803r=0\.803and ICC\(C,1\) = 0\.765 for median posterior log Alpha\. This is initial evidence of within\-subject repeatability, not a population\-level reliability claim\.

Table 1:How to interpret the mini\-dataset validation\.

## 9Step 6: Start the Online Dashboard

For real NeuraDock hardware, the user only needs the hardware stream IP and port:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeonline‘

\-\-ip192\.168\.4\.1‘

\-\-port9600

The agent will connect to the stream, send the device start command, parse packets, run online preprocessing and QC, calculate rolling visual workload, and open the local dashboard:

For a local demo without hardware, run:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeserve\-\-port8765

When no\-\-demo\-fileis supplied, this command generates a deterministic synthetic replay\. A reader can therefore test the UI without NeuraDock hardware or human EEG data\. Open:

If the dashboard is open but no points are visible yet, pressStartin the UI or advance the demo stream manually:

Invoke\-RestMethodhttp://127\.0\.0\.1:8765/api/demo/next

The tutorial screenshot below was captured from the local demo dashboard\. It shows a rolling load index, Alpha state, Alpha peak, quality status, Alpha metrics, and the online preprocessing panel\.

![Refer to caption](https://arxiv.org/html/2606.26518v1/tutorial_online_dashboard_demo.png)Figure 10:Local demo dashboard UI\. This screenshot does not require hardware; the current public command uses a deterministic synthetic replay\.Dashboard fields to inspect:

- •Rolling visual workload index\.
- •Alpha state: weak Alpha, baseline Alpha, or strong Alpha\.
- •Alpha peak frequency\.
- •Alpha suppression from rolling baseline\.
- •Quality status and bad\-channel candidates\.
- •Stream status and samples received\.

The online parser is tuned for the NeuraDock stream profile: 250 Hz sampling, 5 samples per Bluetooth packet, a TCP bridge, and a 4 s rolling analysis window\. Another EEG system can be connected only if its stream is adapted into the expected seven\-channel sample matrix and packet semantics\. Otherwise, the parser and QC assumptions should be treated as hardware\-specific implementation details rather than generic EEG defaults\.

## 10Step 7: Use the Real\-Time API in an Application

After startingonlineorserve, check status:

Invoke\-RestMethodhttp://127\.0\.0\.1:8765/api/status

User applications can read the latest computed workload from:

GEThttp://127\.0\.0\.1:8765/api/status

Important fields:

status

current\.visual\_load\_index

current\.alpha\_state

current\.alpha\_peak\_hz

current\.alpha\_suppression\_from\_baseline

current\.alpha\_asymmetry\_right\_minus\_left

current\.quality\_status

quality\.status

quality\.bad\_channel\_candidates

stream\.connected

stream\.samples\_received

Minimal Python integration:

importrequests

data=requests\.get\("http://127\.0\.0\.1:8765/api/status",timeout=2\)\.json\(\)

ifdata\["status"\]=="ok"anddata\["quality"\]\["status"\]=="pass":

workload=data\["current"\]\["visual\_load\_index"\]

alpha\_state=data\["current"\]\["alpha\_state"\]

alpha\_peak=data\["current"\]\["alpha\_peak\_hz"\]

print\(workload,alpha\_state,alpha\_peak\)

Recommended integration pattern:

NeuraDockhardware

\-\>neuradock\-agentonline

\-\>GET/api/status

\-\>userapplication

### 10\.1Latency Benchmark

The reference tutorial run used a local replay with a 4 s rolling window and 1 s step\. Quality\-valid online steps showed median core processing latency of 1\.89 ms and p95 latency of 2\.66 ms\. The local HTTP demo endpoint showed median latency of 15\.15 ms and p95 latency of 27\.18 ms\. The current no\-hardware command uses a deterministic synthetic replay, so these historical measurements should be treated as reference values rather than guaranteed deployment latency\.

This benchmark measures local computation and API serving, not physical wireless latency, browser rendering, or external application delay\. The practical update cadence is dominated by the configured analysis step and window length\.

### 10\.2Industrial Translation

For teams building adaptive UI, XR interaction prototypes, rehabilitation\-device workflows, driver\-monitoring or HMI research systems, and learning dashboards, the useful interface is deliberately simple\. The/api/statusendpoint returns a 0–100current\.visual\_load\_indexand a quality flag at the online update cadence\. Applications should gate interventions onquality\.statusandcurrent\.quality\_statusbeingpassbefore acting on the load estimate\.

A typical integration rule is:

ifquality\.status=="pass"

andcurrent\.quality\_status=="pass"

andcurrent\.visual\_load\_index\>threshold

forNconsecutivewindows:

adaptinterface

else:

holdstate,continuemonitoring,orrequestrecalibration

This is the commercial translation of the agent’s design: the same QC gate used for research figures can also prevent an application from reacting to noisy real\-time estimates\.

## 11Step 8: Ask for LLM Interpretation

The LLM mode is an explanation layer\. It does not compute EEG features and does not receive raw EEG arrays\. It receives allowlisted summaries, warnings, and interpretation limits\.

Example offline explanation command:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeask‘

"CompareRestandTaskvisualcognitiveloadandexplainqualityrisks"‘

\-\-filedata\_examples\\rest\_task\\rest\_S01\_1\.txt‘

\-\-file2data\_examples\\rest\_task\\task\_S01\_1\.txt‘

\-\-llm‘

\-\-output\-rootruns\\tutorial\_llm

Example Alpha dynamics explanation:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeask‘

"AnalyzeAlphadynamicsandexplaincognitive\-loadrisklimits"‘

\-\-filedata\_examples\\alpha\\open\_closed\_eye2\.txt‘

\-\-llm

A good LLM interpretation should say what the computed values suggest, what quality risks exist, and what conclusions should not be drawn\. For example, ifquality\.statusis warning or a posterior channel is listed as a bad\-channel candidate, the summary should reduce confidence rather than hide the issue\.

### 11\.1Reference LLM Interpretation

One reference tutorial run used an OpenAI\-compatible API endpoint and modelqwen3\.7\-max\. A current run writes the interpretation under the selected output root:

runs/tutorial\_llm/

<run\-id\>\_visual\_cognitive\_load\_comparison/

llm\_interpretation\.md

The archived June 2026 reference file reported the metadata below\. Its context version predates the current2026\.6\.24release:

Status:success

Model:qwen3\.7\-max

Promptversion:neuradock\-result\-interpretation\-v3

Contextversion:2026\.6\.18

Generatedat:2026\-06\-22T11:18:12\+08:00

RawEEGsenttomodel:no

The following excerpt is copied from the real generated LLM interpretation, with the warning symbol removed for LaTeX portability:

> Data Quality Warning\.Signal quality is limited in both conditions, particularly during the Task\. The Task recording retained only 78\.9% of samples after segment QC, and the system detected slight body activity or mild muscle tension\. Forty out of 87 Task windows were excluded because they did not meet the 80% clean\-sample requirement\. The Rest recording had better sample retention at 93\.3%, but 25 out of 102 windows were still excluded\. Because nearly half of the Task windows and a quarter of the Rest windows were excluded, temporal coverage is sparse\. This reduces confidence in continuous tracking of cognitive load\. Main Findings\.The median posterior log Alpha power was slightly lower during Task \(1\.12\) compared with Rest \(1\.14\), yielding a Task\-to\-Rest power ratio of 0\.95 and a difference of \-0\.024\. This small decrease is consistent with Alpha suppression, a common sensor\-level pattern when transitioning from a relaxed state to a visual or cognitive task\. The median Alpha peak frequency shifted slightly higher during Task, from 11\.0 Hz to 11\.25 Hz\. Posterior left/right Alpha asymmetry magnitude was also slightly higher during Task\. Boundary\.Lower Task posterior Alpha is consistent with stronger Alpha suppression, but it does not by itself prove higher cognitive load or establish a causal conclusion\. Visual cognitive\-load labels and indices are relative, within\-recording research heuristics\. They are not medical, psychological, attention, fatigue, or performance diagnoses\.

This real output illustrates the intended LLM role: it summarizes deterministic EEG results, foregrounds quality risks, and states scientific boundaries\. It does not compute the Alpha features and it does not receive raw EEG\.

## 12Troubleshooting

### 12\.1PowerShell Prints a profile\.ps1 Warning

Some Windows environments print a warning such as:

profile\.ps1cannotbeloadedbecauserunningscriptsisdisabled

This warning comes from the local PowerShell profile loading policy\. It does not necessarily mean the NeuraDock command failed\. Check the actual command output and generated files\.

### 12\.2LLM Output File Exists but PowerShell Shows an Encoding Error

On some Windows systems, PowerShell may fail to print Unicode symbols from an LLM interpretation, for example:

’gbk’codeccan’tencodecharacter\.\.\.

Ifllm\_interpretation\.mdwas created, the LLM call itself succeeded\. Open the Markdown file in a UTF\-8 editor, or read it with:

Get\-Contentruns\\YOUR\_RUN\_ID\\llm\_interpretation\.md\-EncodingUTF8

The tutorial run encountered this exact console\-encoding issue after successfully saving the LLM interpretation file\.

### 12\.3The Dashboard Port Is Already Used

Use a different dashboard port:

\.\\\.venv\\Scripts\\neuradock\-agent\.exeonline‘

\-\-ip192\.168\.4\.1‘

\-\-port9600‘

\-\-dashboard\-port8766

### 12\.4The Online API Has No Data

Check:

- •Whether the hardware IP and port are correct\.
- •Whether the stream is connected in/api/status\.
- •Whether samples are being received\.
- •Whether the buffer is still warming up for the first 4 s window\.
- •Whether QC warnings are preventing high\-confidence interpretation\.

### 12\.5Retention Is Low

Low retention means a large fraction of samples or windows failed QC\. Treat downstream Alpha or workload estimates as lower confidence\. Inspectreport\.md,results\.json, and quality figures before interpreting the result\.

### 12\.6Mixed\-Eye Data Needs Caution

Eye state strongly affects posterior Alpha\. Mixed\-eye recordings can be useful for stress\-testing the agent, but they should not be interpreted like clean eyes\-open or eyes\-closed protocol data\. The mini\-dataset intentionally keeps mixed\-eye caveats visible\.

### 12\.7Running Without Hardware

Readers without NeuraDock hardware can still run most of the tutorial\. Synthetic replay supports the demo dashboard,/api/status, and/api/demo/next; downloaded public TXT files support preprocessing, QC reports, Alpha dynamics, offline Rest/Task comparison, mini\-dataset analysis, and LLM interpretation\. These modes cannot validate the physical wireless path: Bluetooth throughput, TCP bridge behavior, packet loss, device start command behavior, or end\-to\-end hardware latency\.

### 12\.8Dependency Conflicts

For a clean developer environment, use a fresh virtual environment:

Remove\-Item\-Recurse\-Force\.venv

py\-mvenv\.venv

\.\\\.venv\\Scripts\\python\.exe\-mpipinstall\-\-upgradepip

\.\\\.venv\\Scripts\\python\.exe\-mpipinstall\-e"\.\[dev\]"

Then run the focused tests:

\.\\\.venv\\Scripts\\python\.exe\-mpytest\-q‘

tests\\test\_workflows\.pytests\\test\_online\.py

### 12\.9Docker Status

This first open\-source release does not bundle an official Docker image\. The supported reproducible path is the Python virtual environment shown in Step 1\. A future Docker workflow should preserve the same CLI entry points and keep raw EEG local unless the user explicitly configures external services\.

### 12\.10Extending or Contributing

Developers who want to extend the workflow should start fromCOMMANDS\.md,CONTRIBUTING\.md,src/neuradock\_agent/workflows\.py, andsrc/neuradock\_agent/cli\.py\. New analysis features should keep the same rule as the built\-in workflows: compute downstream metrics from the preprocessing/QC\-gated path and expose quality risks alongside any workload estimate\.

### 12\.11pdflatex Is Not Installed

The tutorial source is a standardLaTeXfile\. To render a PDF, install a TeX distribution such as TeX Live or MiKTeX, open a terminal in the directory containing this file, then run:

pdflatexneuradock\_visual\_cognitive\_load\_agent\_tutorial\_20260618\.tex

pdflatexneuradock\_visual\_cognitive\_load\_agent\_tutorial\_20260618\.tex

## 13Discussion

### 13\.1What the Tutorial Demonstrates

This tutorial demonstrates an offline\-to\-online bridge\. A reader can start from a static EEG file, pass through preprocessing and QC, inspect Alpha dynamics, compare rest and task within subject, run the public mini\-dataset analyses and compare them with the reference summary, and then use the same conceptual pipeline in a real\-time dashboard and API\.

The most important scientific design choice is that all downstream interpretation depends on quality\-gated data\. This makes the agent more conservative but more credible\. The agent does not simply output a workload score; it reports whether the signal quality supports interpretation\.

The hardware design is part of the same argument\. The posterior NeuraDock montage concentrates sensors around visual Alpha generators, while the online parser and rolling\-window defaults match the NeuraDock data\-throughput profile\. This makes the tutorial more than a generic EEG script collection: it is a hardware\-tuned, application\-facing workflow for visual cognitive\-load prototypes\.

### 13\.2Comparison With Existing Tools

Table 2:Tutorial positioning relative to existing EEG tools and device ecosystems\.This table is not a replacement claim\. MNE\-Python, BrainFlow, and EEGLAB remain valuable foundations\. NeuraDock Agent is useful because it narrows the workflow to a specific applied problem: visual cognitive load from quality\-gated Alpha dynamics\.

### 13\.3Limitations

The mini\-dataset is small and should be understood as a tutorial validation set, not a population\-level scientific study\. The online benchmark used local demo replay rather than physical wireless hardware\. The current workload estimate is primarily based on posterior Alpha dynamics and does not yet integrate behavioral accuracy, reaction time, subjective workload scales, pupil size, or multimodal physiology\. Larger protocol\-controlled validation is necessary before deployment in high\-stakes contexts\.

## 14Conclusion

NeuraDock Agent is best understood as a focused, open\-source tutorial workflow for visual cognitive\-load EEG\. It guides a reader from installation to preprocessing, Alpha dynamics, offline within\-subject comparison, public mini\-dataset analysis, online dashboard/API use, and LLM explanation\. The tutorial format makes the system’s value concrete: readers can run the commands, inspect the generated figures, verify that metrics are quality\-gated, and integrate the real\-time API into their own applications\. For developers extending the workflow,COMMANDS\.mdandCONTRIBUTING\.mdprovide the starting point; new features should preserve the agent’s central promise: cognitive\-load estimates are useful only when paired with transparent signal\-quality evidence\.

## Reproducibility Checklist

- •
- •
- •Main command guide:COMMANDS\.md
- •Contributor guide:CONTRIBUTING\.md
- •Data usage rules:DATASET\.md
- •Verified example downloader:scripts/download\_example\_data\.py
- •Workflow implementation:src/neuradock\_agent/workflows\.py
- •CLI routing:src/neuradock\_agent/cli\.py
- •Realtime API implementation:src/neuradock\_agent/online\.py
- •Automated tests:tests/
- •This tutorial source and its adjacentfigures/directory\.

## Intended Use Statement

NeuraDock Agent outputs are relative research and engineering signals\. They are not medical, clinical, attention, fatigue, cognitive\-ability, or performance diagnoses\. Any deployment that affects users should include protocol control, quality review, informed consent, privacy safeguards, and independent validation\.

## References

- \[1\]MNE\-Python documentation\.[https://mne\.tools/stable/index\.html](https://mne.tools/stable/index.html)
- \[2\]Gramfort A, Luessi M, Larson E, et al\. MEG and EEG data analysis with MNE\-Python\.Frontiers in Neuroscience\. 2013\.[https://doi\.org/10\.3389/fnins\.2013\.00267](https://doi.org/10.3389/fnins.2013.00267)
- \[3\]BrainFlow documentation\.[https://brainflow\.readthedocs\.io/](https://brainflow.readthedocs.io/)
- \[4\]EEGLAB documentation\.[https://eeglab\.org/](https://eeglab.org/)
- \[5\]Delorme A, Makeig S\. EEGLAB: an open source toolbox for analysis of single\-trial EEG dynamics including independent component analysis\.Journal of Neuroscience Methods\. 2004\.[https://doi\.org/10\.1016/j\.jneumeth\.2003\.10\.009](https://doi.org/10.1016/j.jneumeth.2003.10.009)
- \[6\]Emotiv Cortex API documentation\.[https://emotiv\.gitbook\.io/cortex\-api/](https://emotiv.gitbook.io/cortex-api/)
- \[7\]Neurosity documentation\.[https://docs\.neurosity\.co/](https://docs.neurosity.co/)
- \[8\]Klimesch W\. Alpha\-band oscillations, attention, and controlled access to stored information\.Trends in Cognitive Sciences\. 2012\.[https://doi\.org/10\.1016/j\.tics\.2012\.10\.007](https://doi.org/10.1016/j.tics.2012.10.007)
- \[9\]Jensen O, Mazaheri A\. Shaping functional architecture by oscillatory Alpha activity: gating by inhibition\.Frontiers in Human Neuroscience\. 2010\.[https://doi\.org/10\.3389/fnhum\.2010\.00186](https://doi.org/10.3389/fnhum.2010.00186)