Kahlus Biomedical Execution Plan#

RewardDock Clinical Extension Strategy#

Existing at-home and point-of-care saliva workflows already cover cortisol and salivary alpha-amylase collection/readout patterns. RewardDock should not compete as a generic hormone or stress meter; those biosensors are ingredients for a task-specific response-profile product.

Kahlus RewardDock Clinical =

  • standardized task battery

  • webcam pupillometry

  • reaction time / effort behavior

  • optional PPG/HRV

  • optional cortisol / alpha-amylase module

  • Kahlus response-profile model

  • clinician dashboard

Primary clinical wedge:

Adults with anhedonia-related depression or social anxiety who are starting or adjusting treatment.

Need statement:

A way to objectively track reward-response and stress-recovery changes in adults undergoing treatment for anhedonia-related depression or social anxiety in order to help clinicians identify ineffective treatment plans earlier than self-report alone.

The goal is not to replace interviews or self-report. The goal is to add repeated within-person response data under standardized conditions and ask whether a person’s reward/stress/social-response profile is improving relative to their own baseline. It does not ask whether the person has depression, anhedonia, or social anxiety.

Allowed claims:

  • tracks reward-response profile

  • tracks stress-recovery profile

  • tracks within-person change over time

  • supports treatment-response research

  • supports clinician review as an adjunct signal

Blocked claims:

  • diagnoses depression

  • diagnoses anhedonia

  • diagnoses social anxiety

  • recommends medication

  • adjusts medication

  • treats depression

  • treats PTSD

  • replaces clinician judgment

  • claims cortisol/alpha-amylase alone measures anhedonia

RewardDock Biomarker Architecture#

Core v0:

  • webcam pupil dilation

  • reaction time

  • effort persistence

  • task accuracy

  • self-report slider

Core v1:

  • PPG/HRV

  • heart-rate recovery

  • optional EDA

Future biochemical add-on:

  • salivary cortisol

  • salivary alpha-amylase

Avoid as primary:

  • dopamine

  • oxytocin

  • epinephrine/norepinephrine direct measurement

Dopamine, oxytocin, and epinephrine are not practical home biomarkers for this use case because peripheral levels do not cleanly map to central reward circuitry, assays are difficult or context-dependent, and they are not condition-specific enough for RewardDock v0. Cortisol and salivary alpha-amylase are more realistic stress-context add-ons, but they should not be the core product.

RewardDock Device Roadmap#

RewardDock v0:

  • webcam pupil + reward task + reaction time + self-report

RewardDock v1:

  • add PPG/HRV

RewardDock v2:

  • add optional saliva cortisol / alpha-amylase integration

RewardDock v3:

  • clinician dashboard + longitudinal treatment-response report

RewardDock Consumer:

  • future nonclinical self-improvement product only after clinical/research validation

Do not start with self-improvement branding. Start clinical/research first to avoid becoming a generic dopamine-maxxing wellness app.

RD-0: Safe Scaffold#

Deliverables:

  • root technical roadmap docs

  • ResearchDock dataclasses

  • safe task templates

  • deterministic synthetic sessions

  • numpy-only metrics

  • synthetic data card

  • branch-specific evidence gate

  • local smoke script

Acceptance:

  • no frozen v1 load-bearing files modified

  • no A100 or cluster jobs

  • no hardware access

  • no real participant data

  • no clinical claims

  • tests pass

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_synth
git diff --check -- ':!graphify-out'

RD-1: Task App Prototype#

  • task flow for reward anticipation, effort-for-reward, mild frustration, recovery, and visual attention

  • webcam/pupil interface design

  • optional PPG/HRV input schema

  • CSV/session export

  • quality flags

No clinical claims and no treatment tasks.

RD-1 local implementation scope:

  • deterministic task/session protocol in code

  • design-only webcam pupil/gaze and optional PPG/HRV interface contract

  • no camera or PPG device opened in tests or scripts

  • CSV export for sessions, trials, sensor packets, task events, and self-report

  • quality-flag summaries for missing pupil, invalid pupil, implausible reaction time, and invalid accuracy

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd1 --seed 0 --write-session-export

RD-2: Kahlus v2 Multimodal Observation Model#

  • synthetic pupil + behavior + PPG pretraining

  • observation operators for pupil, HRV, behavior, and EEG

  • subject adapter design

  • missing-modality tests

Baselines must run before any Kahlus model comparison.

RD-2 local implementation scope:

  • synthetic ResearchDock multimodal observation task with subject-held-out sessions

  • behavior/task/self-report features predict pupil and HRV proxy targets

  • mean and ridge baselines run before the ResearchDock observation-operator candidate

  • NumPy low-rank residual observation operator with a simple subject-adapter offset

  • synthetic pretraining artifact writer; no real data, no EEG hardware, and no clinical claims

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd2 --seed 0 --run-observation-model

RD-3: Public Dataset Ingestion Review#

  • WESAD feature mapping

  • DEAP feature mapping

  • SEED feature mapping

  • data terms and citation verification

  • no invented URLs or loaders

RD-3 local implementation scope:

  • source-backed review registry for WESAD, DEAP, and SEED

  • ResearchDock field mappings for physiology, EEG, eye-tracking, self-report, and stimulus context

  • explicit access and license uncertainty where terms are not fully resolved

  • JSON and Markdown review artifacts

  • no dataset downloads, no executable loaders, no raw participant data, and no clinical claims

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd3 --seed 0 --write-public-dataset-review

RD-4: Pilot Readiness Preflight#

  • validation-scale pilot manifest

  • required prior evidence checklist

  • pre-collection safety gate

  • operator checklist for storage, identifier handling, and artifact archival

  • no legal advice, no real participant data, no hardware access, no collection, and no clinical claims

RD-4 local implementation scope:

  • build a JSON-compatible ResearchDock pilot manifest from synthetic fixtures and the RD-1 protocol

  • require RD-0 synthetic gate, RD-1 export contract, RD-2 baseline artifacts, and RD-3 dataset review before any pilot path

  • block hardware access, real participant data, PII, clinical labels, stimulation, trauma exposure tasks, and diagnostic/treatment claims

  • write manifest, preflight gate, and Markdown report artifacts

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd4 --seed 0 --write-pilot-preflight

RD-5: Response-Profile Readiness Audit#

  • future latent response-profile clustering is audited for data readiness only

  • no clustering is performed, no cluster labels are emitted, and no clinical claims are supported

  • the audit checks profile-vector finiteness, minimum validation-scale session count, observed quality flags, and missing-pupil blockers

  • synthetic RD-5 output is expected to fail readiness honestly because it is tiny and includes a missing-pupil profile

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd5 --seed 0 --write-profile-readiness

RD-6: Observation Missing-Modality Audit#

  • RD-2 observation-task construction now reports how many synthetic trials are eligible versus skipped

  • skipped trials are counted by missing sensor packet, pupil diameter, HRV proxy, and behavior-response fields

  • the observation task JSON, metrics JSON, and Markdown report expose the audit instead of silently dropping missing-modality rows

  • no imputation, clustering, hardware access, real participant data, or clinical claims are introduced

Verification:

PYTHONPATH=src python3 -m unittest discover -s tests/researchdock -v
PYTHONPATH=src python3 scripts/run_researchdock_synthetic.py --out-dir /tmp/kahlus_researchdock_rd6 --seed 0 --run-observation-model

A100-0: 7xA100 Handoff Readiness Package#

  • exact commit hash

  • clean worktree proof

  • runner tarball

  • config files

  • checksum manifest

  • CPU smoke command

  • DDP/torchrun command

  • honest GPU count labeling: 7xA100, not 8xA100

  • evidence bundle writer and returned-evidence audit command

  • no secrets, checkpoints, raw arrays, or raw private participant data

A100-0 local implementation scope:

  • package only from a clean git worktree; dirty worktrees fail instead of fabricating proof

  • write COMMIT_HASH.txt, CLEAN_WORKTREE.txt, A100_HANDOFF_MANIFEST.json, README_A100_7X_HANDOFF.md, SHA256SUMS, and a runner tarball

  • set --nproc_per_node=7 and --expected-gpus 7

  • do not launch A100, Slurm, Docker, torchrun, dataset downloads, or full sweeps

  • keep claims at infrastructure handoff only

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-1: 7xA100 Returned-Evidence Audit Default#

  • default returned-evidence audit expectation is 7 visible GPUs

  • 7-GPU synthetic evidence passes without requiring an explicit override

  • 8-GPU evidence fails by default unless the caller intentionally overrides --expected-gpus

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_audit_ktm_a100_evidence -v

A100-2: Runner Self-Smoke Importability#

  • the 7xA100 runner tarball includes the script bootstrap helper needed by packaged CLI scripts

  • the packaged returned-evidence audit script can print --help from inside an extracted runner

  • the runner still excludes secrets, checkpoints, raw arrays, raw private participant data, and graph outputs

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-3: Runner Evidence-Bundle Self-Smoke#

  • the extracted 7xA100 runner can package a tiny returned-evidence zip using its included evidence writer

  • if no handoff README template is available inside the runner, the writer emits a minimal claim-safe README instead of failing

  • the generated evidence README keeps boundaries explicit: no scientific result, no clinical claim, no diagnosis, no treatment, no recovery claim, and no model-superiority claim

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-4: Runner Fail-Closed Audit Round Trip#

  • the extracted 7xA100 runner can audit the tiny self-smoke evidence zip it creates

  • incomplete evidence fails closed with audit JSON and Markdown report artifacts instead of crashing

  • missing required run files are reported with the canonical required_file_missing finding code

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-5: Operator Runner Self-Smoke Command#

  • the 7xA100 handoff manifest and README include a single local runner_self_smoke_command

  • the extracted runner includes scripts/smoke_a100_runner.py

  • the self-smoke creates a tiny evidence zip, audits it, verifies fail-closed report artifacts, and prints runner_self_smoke_passed=true

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-6: Runner Internal Checksum Command#

  • the 7xA100 handoff manifest and README include runner_checksum_command

  • after extracting the runner tarball, shasum -a 256 -c RUNNER_SHA256SUMS verifies runner contents before self-smoke

  • no A100, Slurm, Docker, torchrun, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-7: Extracted Runner CPU Smoke#

  • the advertised cpu_smoke_command is executed from inside the extracted 7xA100 runner during tests

  • the runner includes the minimal neurotwin package initializer and unified gate package needed by ResearchDock tests

  • this verifies the ResearchDock CPU smoke path locally before any A100, Slurm, Docker, torchrun, dataset download, or returned real evidence

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-8: Advertised CLI Train Target Import Smoke#

  • the extracted 7xA100 runner includes neurotwin.cli and the local command/training dependency surface needed by the advertised DDP command target

  • PYTHONPATH=src python3 -m neurotwin.cli train --help runs inside the extracted runner

  • this validates command-target importability only; it does not launch A100, Slurm, Docker, torchrun, training, dataset download, or returned real evidence

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-9: Advertised Train Command Parser Alignment#

  • the 7xA100 DDP command no longer advertises unsupported train --require-pass

  • the extracted runner dry-runs PYTHONPATH=src python3 -m neurotwin.cli train --dry-run --config configs/train/moabb_a100_smoke.yaml

  • this validates command/config parseability only; it does not launch A100, Slurm, Docker, torchrun, training, dataset download, or returned real evidence

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-10: Runner OS Metadata Exclusion#

  • tracked .DS_Store / macOS metadata files are excluded from the handoff and runner tarball

  • the handoff test injects a tracked .DS_Store into a copied source tree and verifies it is not shipped

  • no A100, Slurm, Docker, torchrun, training, dataset download, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

A100-11: Runner Model Artifact Exclusion#

  • tracked serialized model/baseline artifacts such as .safetensors, .onnx, .pkl, .pickle, and .joblib are excluded from the handoff and runner tarball

  • the handoff test injects tracked model artifact fixtures into included source paths and verifies they are not shipped

  • no A100, Slurm, Docker, torchrun, training, dataset download, checkpoint transfer, or returned real evidence is required

Verification:

PYTHONPATH=src python3 -m unittest tests.artifacts.test_kahlus_a100_7x_handoff -v

Long-Term#

  • validation-scale ResearchDock data collection after review

  • v3 perturbation-response training when structured data exists

  • A100 handoff only after local correctness, split audit, baseline ladder, evidence gate, clean merge/tag, smoke run, and returned evidence audit