focux-engines

Open-sourced engines, protocols, and signal processing for state-aware embodied interaction.

This repository collects the technical core of FocuX — a research prototype for continuous, low-interruption state sensing during knowledge work. Each subdirectory is an independently usable engine, protocol, or signal-processing module. The application layer (iOS app, website, voice agent, motor bus arbitration) is intentionally not included here.

What's inside

focux-engines/
├── core/                    # Protocols and shared abstractions
│   ├── sensor-module/         SensorModule ABC + ModuleReading interface
│   ├── context-bus/           In-process pub/query bus with TTL signals
│   └── harness-protocol/      SubjectStateFrame schema + WS broadcast spec
│
├── engines/                 # The judgment layer
│   ├── stamina/               EMG → 3-dimensional stamina (0–100)
│   ├── vision/                MediaPipe BlendShapes → PERCLOS / blink / yawn / head pose
│   ├── fusion/                N-source quality-weighted fusion + hierarchical override
│   ├── intervention/          silent_log → light_nudge → escalation policy
│   ├── breath/                10 Hz breath orchestrator (color temperature + phase integration)
│   ├── fatigue/               MDF spectral-shift fatigue estimator
│   └── decision/              Stamina → human-readable recommendation
│
├── signals/                 # Low-level signal processing
│   ├── emg-features/          84-dim feature extraction (RMS / MDF / ZC / WL / SSC / MNF …)
│   └── canonical/             8-channel signal canonicalisation
│
├── models/                  # Algorithms with trained components (weights via Releases)
│   ├── emotion-hand-wesad/    LightGBM emotion recognition on WESAD
│   └── onnx-inference/        Real-time ONNX inference chain
│
├── hardware/                # Acquisition firmware
│   └── echowrist/             ESP32-C3 dual-channel EMG + GSR
│
├── consumers/               # Reference implementations of harness consumers
│   └── lelamp-listener/       LeLamp-side listener: gate, debounce, budget, recovered loop
│
└── docs/                    # Cross-cutting design notes

Model weights are distributed via GitHub Releases, not committed to the repo.

Design stance

Five positions guide the work in this repo:

1. Log before speaking — first anomalies enter silent_log, not visible output.
2. Evidence before interruption — every visible action requires cross-modal evidence.
3. Graded appearance — silent_log → light_nudge → escalation. Intensity is a design choice.
4. Body before screen — light, posture, rhythm, breath precede pop-ups.
5. Relationship over single reminder — value compounds across sessions, not single hits.

Status

This is a research prototype companion repository.

Module	Status	Tests	SOTA reference
engines/fusion	imported	32	Han et al. 2024 QMF
engines/intervention	imported	40	Tewari & Murphy 2017; Karine & Marlin 2024
engines/stamina	imported	48	De Luca 1997; Yan et al. PLOS One 2024
engines/breath	imported	22	Bouny et al. Sensors 2023; Lehrer & Vaschillo
engines/vision	imported	18	Schleicher 2008 (P80)
all other modules	planned	—	—

Cumulative: 160 passing tests, 5 pip-installable Python packages, CI green.

License

Apache License 2.0. Patent grant included.

Citation

If this work supports your research, citation guidance will be added once the related papers are published.

Not included here

• iOS application source
• focux.me website
• Editorial / branding assets
• Authoring toolchain (Quarto, Vale rules, Claude skills)
• LeLamp motor bus arbitration and voice agent (separate hardware-ownership boundary)