feat(stamina): import StaminaEngine v0.1.0 (status: imported)

Three-dimensional EMG stamina with temporal attention and
variance-derived confidence. Pure numpy, no training, deterministic.

Dimensions (each in [0, 1]):
  - pattern_consistency  — CoV of RMS over recent windows
  - baseline_tension     — RMS above resting baseline
  - sustained_capacity   — MDF leftward drift (De Luca 1997)

Per-window features (RMS, MDF) feed three independent dimension
extractors. Dimensions are aggregated across recent windows with
exponential-decay attention (closed-form alternative to the learned
attention in Yan et al. PLOS One 2024 — same intuition, no training).
The linear combination drives a stamina accumulator that drains in
work and recovers in rest.

API:
  - StaminaState enum (focused / fading / depleted / recovering / unknown)
  - FatigueDimensions dataclass with per-axis fatigue evidence
  - StaminaReading dataclass (stamina, state, confidence, dimensions, notes)
  - StaminaConfig (sample rate, window size, weights, thresholds)
  - StaminaEngine.update(samples, *, now) → StaminaReading
  - save_state / load_state / compute_offline_recovery for persistence
  - Standalone feature helpers (rms, median_frequency, pattern_consistency,
    baseline_tension, sustained_capacity)
  - Standalone attention helpers (exponential_decay_weights,
    weighted_aggregate, confidence_from_variance)

48 passing tests across features, attention, and engine.

Demo: examples/demo.py — 60-second synthetic session with rising
amplitude and falling MDF; exercises all three dimensions and
persistence roundtrip.

Status: engines/stamina → imported. Cumulative: fusion + intervention
+ stamina all imported. Other modules remain planned.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: wujiajunhahah

engines/stamina/README.md

@@ -1,38 +1,132 @@
 # stamina engine
 
-**Status:** `planned`
+**Status:** `imported` · v0.1.0 · Apache-2.0
 
-Turns 8-channel EMG into a stamina score (0–100) and a 4-state state machine.
-Not a linear regression — three independent dimensions with explicit theoretical grounding.
+Three-dimensional EMG-based stamina estimation with **temporal attention**
+(exponential-decay weighting) and **variance-derived confidence**. Pure
+numpy, no training, fully deterministic.
 
-## Three dimensions
+## What it computes
 
-| Dimension | Weight | What it captures | Reference |
-|---|---|---|---|
-| Pattern Consistency | 0.40 | Coefficient of variation of RMS over a 30 s window — proxy for sustained focus | — |
-| Baseline Tension | 0.25 | Residual muscle tone above rest baseline | — |
-| Sustained Capacity | 0.35 | Median frequency (MDF) drift over time — physiological fatigue | De Luca, 1997 |
+For each analysis window (default 250 ms of EMG samples) the engine
+extracts:
 
-## State machine
+- **RMS** — root mean square amplitude
+- **MDF** — median frequency of the power spectrum (De Luca, 1997)
 
+…then reduces them into three independent fatigue dimensions:
+
+| Dimension | Source | What it captures |
+|---|---|---|
+| Pattern Consistency | CoV of RMS over recent windows | Motor pattern stability |
+| Baseline Tension | RMS / resting-baseline RMS | Residual carried tension |
+| Sustained Capacity | MDF leftward drift vs. baseline | Spectral fatigue (De Luca 1997) |
+
+Each dimension is normalised to [0, 1] and aggregated across recent
+windows using **exponential decay** (newest window weight 1.0, with a
+configurable half-life). The aggregate is then linearly combined into a
+fatigue score that drives a stamina accumulator (drains in work, recovers
+in rest), and finally classified into a state.
+
+## What's new vs. a plain three-dimensional sum
+
+Compared to a flat per-window combination, this engine adds:
+
+1. **Temporal attention** via exponential decay. Recent windows weigh
+   more than older ones — addresses the same intuition as the multilevel
+   attention mechanism in *Yan et al., PLOS One 2024* on sEMG fatigue
+   recognition, in closed form and without training.
+2. **Variance-based confidence**. Every reading carries a confidence
+   score derived from per-window RMS variance. Sparse or extremely
+   noisy data automatically reduces downstream trust.
+3. **Per-dimension audit**. Two readings can both be `stamina=55` but
+   come from very different dimension breakdowns. Consumers (e.g. the
+   intervention engine) can read each dimension to differentiate
+   "motor pattern unstable, needs rest" from "baseline tension high,
+   needs relaxation".
+4. **Persistence**. `save_state()` / `load_state()` / `compute_offline_recovery()`
+   survive process restarts and resume with a sensible estimate of
+   recovery during downtime.
+
+## Install
+
+```bash
+cd engines/stamina
+pip install -e .
 ```
-focused (>60) → fading (30–60) → depleted (<30) → recovering
+
+## Use
+
+```python
+from focux_stamina import StaminaConfig, StaminaEngine
+import numpy as np
+import time
+
+cfg = StaminaConfig(sample_rate_hz=1000.0, window_size_sec=0.25)
+engine = StaminaEngine(cfg)
+
+# every 250 ms of EMG samples, push them through:
+samples = np.array([...])  # one window
+reading = engine.update(samples, now=time.time())
+
+print(reading.stamina, reading.state.value, reading.confidence)
+print(reading.dimensions.to_dict())
+# {'pattern_consistency': 0.21,
+#  'baseline_tension':    0.45,
+#  'sustained_capacity':  0.12}
 ```
 
-## Accumulator behaviour
+See [`examples/demo.py`](examples/demo.py) for a full 60-second synthetic
+session that ramps up fatigue and exercises every dimension.
+
+## Public API
+
+| Name | Purpose |
+|---|---|
+| `StaminaState` | Enum: focused / fading / depleted / recovering / unknown |
+| `FatigueDimensions` | Per-axis breakdown (`pattern_consistency`, `baseline_tension`, `sustained_capacity`) |
+| `StaminaReading` | Engine output dataclass with `stamina`, `state`, `confidence`, `dimensions`, `notes` |
+| `StaminaConfig` | All sample/window/weight/threshold parameters |
+| `StaminaEngine` | `update(samples, *, now)`, `save_state()`, `load_state(snap)`, `compute_offline_recovery(elapsed_sec)`, `current_stamina` |
+| `rms`, `median_frequency`, `pattern_consistency`, `baseline_tension`, `sustained_capacity` | Standalone feature helpers |
+| `exponential_decay_weights`, `weighted_aggregate`, `confidence_from_variance` | Attention helpers |
+
+## Tests
+
+```bash
+pip install -e .[test]
+pytest
+```
 
-- Working state: stamina decreases at `drain_rate × (0.5 + fatigue_multiplier)`
-- Resting state: recovers at `recovery_rate`
-- Supports persistence: save / load state, compute natural recovery while offline
+48 tests covering: RMS / MDF on zero / empty / sine / dominant-frequency
+inputs; pattern consistency, baseline tension, sustained capacity edge
+cases (empty / constant / drop magnitudes); exponential decay weights
+(half-life correctness, monotonicity, degenerate zero half-life);
+weighted aggregate; confidence-from-variance; engine initial state,
+drain in work, recover in rest, state classification at thresholds,
+dimensions within unit interval, variable-amplitude increases pattern
+dimension, persistence roundtrip, offline recovery cap at 100,
+confidence within unit interval.
 
-## Why three dimensions instead of one number
+## Design decisions
 
-The same stamina = 60 can come from *unstable pattern* (rest needed) or *accumulated tension*
-(relaxation needed) or *spectral fatigue* (stop working). Downstream policies need to differentiate.
+- **No neural net.** Exponential decay is the closed-form, training-free
+  version of "attention over recent windows". For sEMG fatigue the
+  marginal accuracy of a learned attention layer doesn't justify the
+  audit-trail loss.
+- **Three dimensions, kept separate.** Same `stamina` value can mean
+  different things; downstream policies need to differentiate them.
+- **Calibration is automatic.** The first few seconds of low-activity
+  data populate per-user baselines for RMS and MDF. The engine reports
+  `baseline_pending` in `notes` until calibration completes.
+- **Persistence over process boundary.** The engine is the
+  user's continuous state record — it must survive restarts.
 
-## To be imported
+## References
 
-- `StaminaEngine` core class
-- `StaminaReading` dataclass + state enum
-- Persistence helpers (`save_state` / `load_state` / `compute_offline_recovery`)
-- Unit tests covering each dimension and the state transitions
+- De Luca, C. J. *The Use of Surface Electromyography in Biomechanics.*
+  J Applied Biomechanics, 1997. (MDF as fatigue marker)
+- Yan, X. et al. *Multilevel attention mechanism for motion fatigue
+  recognition based on sEMG and ACC signal fusion.* PLOS One, 2024.
+- Park, J. et al. *A Multimodal Fatigue Detection System Using sEMG
+  and IMU Signals with a Hybrid CNN-LSTM-Attention Model.* Sensors, 2025.

engines/stamina/examples/demo.py

@@ -0,0 +1,79 @@
+"""Demo: walk a synthetic 60-second EMG session through StaminaEngine.
+
+The first 5 seconds are resting baseline. The next 55 seconds simulate
+working activity with rising amplitude (increasing tension) and falling
+median frequency (spectral fatigue) — i.e. all three fatigue dimensions
+should trend up.
+
+Run:
+
+    pip install -e .
+    python examples/demo.py
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from focux_stamina import StaminaConfig, StaminaEngine
+
+
+def main() -> None:
+    rng = np.random.default_rng(seed=7)
+    cfg = StaminaConfig(
+        sample_rate_hz=1000.0,
+        window_size_sec=0.25,
+        drain_rate_per_sec=1.5,
+        recovery_rate_per_sec=0.5,
+    )
+    eng = StaminaEngine(cfg)
+
+    print("StaminaEngine demo — 60s synthetic session")
+    print("  first 5s = rest baseline; remaining 55s = working with rising fatigue\n")
+    print(f"  {'t(s)':>5}  {'rms':>6}  {'mdf(Hz)':>8}  "
+          f"{'stamina':>8}  {'state':<10}  "
+          f"{'pc':>5}  {'bt':>5}  {'sc':>5}  conf")
+    print(f"  {'-'*5}  {'-'*6}  {'-'*8}  {'-'*8}  {'-'*10}  "
+          f"{'-'*5}  {'-'*5}  {'-'*5}  ----")
+
+    now = 0.0
+    n_windows = int(60.0 / cfg.window_size_sec)
+    for i in range(n_windows):
+        t_now = i * cfg.window_size_sec
+        if t_now < 5.0:
+            samples = rng.normal(0, 0.01, cfg.window_samples)
+        else:
+            # ramping amplitude + falling MDF
+            ramp = (t_now - 5.0) / 55.0
+            amp = 0.2 + 0.5 * ramp + rng.normal(0, 0.05)
+            target_freq = 120.0 - 70.0 * ramp
+            t = np.arange(cfg.window_samples) / cfg.sample_rate_hz
+            samples = amp * np.sin(2 * np.pi * target_freq * t) + rng.normal(
+                0, 0.02, cfg.window_samples
+            )
+        now += cfg.window_size_sec
+        r = eng.update(samples, now=now)
+        if i % 16 == 0 or i == n_windows - 1:
+            d = r.dimensions
+            print(
+                f"  {t_now:5.1f}  {(samples**2).mean()**0.5:6.3f}  "
+                f"{0.0:8.1f}  "
+                f"{r.stamina:8.2f}  {r.state.value:<10}  "
+                f"{d.pattern_consistency:5.2f}  "
+                f"{d.baseline_tension:5.2f}  "
+                f"{d.sustained_capacity:5.2f}  "
+                f"{r.confidence:4.2f}"
+            )
+
+    print()
+    print(f"Final stamina: {eng.current_stamina:.2f}")
+    snap = eng.save_state()
+    print(f"Saved state snapshot keys: {sorted(snap.keys())}")
+    eng2 = StaminaEngine(cfg)
+    eng2.load_state(snap)
+    eng2.compute_offline_recovery(elapsed_sec=60.0)
+    print(f"After 60s offline recovery: {eng2.current_stamina:.2f}")
+
+
+if __name__ == "__main__":
+    main()

engines/stamina/focux_stamina/__init__.py

@@ -0,0 +1,29 @@
+"""focux_stamina — three-dimensional EMG stamina engine with temporal attention."""
+
+from .attention import exponential_decay_weights, weighted_aggregate
+from .config import StaminaConfig
+from .engine import StaminaEngine
+from .features import (
+    baseline_tension,
+    median_frequency,
+    pattern_consistency,
+    rms,
+    sustained_capacity,
+)
+from .types import FatigueDimensions, StaminaReading, StaminaState
+
+__all__ = [
+    "StaminaConfig",
+    "StaminaEngine",
+    "StaminaReading",
+    "StaminaState",
+    "FatigueDimensions",
+    "rms",
+    "median_frequency",
+    "pattern_consistency",
+    "baseline_tension",
+    "sustained_capacity",
+    "exponential_decay_weights",
+    "weighted_aggregate",
+]
+__version__ = "0.1.0"

engines/stamina/focux_stamina/attention.py

@@ -0,0 +1,72 @@
+"""Lightweight temporal attention for sequential windows.
+
+We do not use neural attention. Just an exponential decay over time:
+the most recent window gets weight 1.0, and earlier windows fade with
+a configurable half-life.
+
+This addresses the same intuition as multilevel attention in PLOS One
+2024 (Yan et al.) for sEMG fatigue recognition — the network's attention
+heatmap also concentrates on recent windows for fatigue-onset detection.
+Exponential decay is the closed-form, training-free version: cheap,
+deterministic, and good enough when the underlying features are
+already strong.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Sequence
+
+import numpy as np
+
+
+def exponential_decay_weights(
+    n_windows: int, half_life_windows: float
+) -> np.ndarray:
+    """Return weights for `n_windows` windows ordered oldest → newest.
+
+    The newest window (index -1) gets weight 1.0; the window
+    `half_life_windows` steps before it gets weight 0.5.
+    """
+    if n_windows <= 0:
+        return np.array([], dtype=float)
+    if half_life_windows <= 0:
+        # degenerate: only the newest window has weight
+        w = np.zeros(n_windows, dtype=float)
+        w[-1] = 1.0
+        return w
+    decay = math.log(2.0) / half_life_windows
+    indices = np.arange(n_windows)
+    age = (n_windows - 1) - indices  # 0 for newest, n-1 for oldest
+    return np.exp(-decay * age)
+
+
+def weighted_aggregate(
+    values: Sequence[float], half_life_windows: float
+) -> float:
+    """Single-scalar weighted aggregate of a sequence with exponential decay.
+
+    Returns 0.0 for empty input.
+    """
+    if not values:
+        return 0.0
+    arr = np.asarray(values, dtype=float)
+    w = exponential_decay_weights(arr.size, half_life_windows)
+    total = w.sum()
+    if total == 0:
+        return 0.0
+    return float((arr * w).sum() / total)
+
+
+def confidence_from_variance(values: Sequence[float]) -> float:
+    """Map per-window variance into a [0, 1] confidence score.
+
+    Low variance → high confidence (the engine is sure about the signal).
+    Uses a soft saturation: variance ≥ 0.25 maps to confidence 0.0;
+    variance == 0 maps to confidence 1.0.
+    """
+    if not values or len(values) < 2:
+        return 0.0
+    arr = np.asarray(values, dtype=float)
+    v = float(arr.var())
+    return float(max(0.0, 1.0 - v / 0.25))

engines/stamina/focux_stamina/config.py

@@ -0,0 +1,45 @@
+"""StaminaEngine configuration. All thresholds and weights in one place."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class StaminaConfig:
+    sample_rate_hz: float = 1000.0
+    """EMG sample rate (Hz)."""
+
+    window_size_sec: float = 0.25
+    """Length of one analysis window in seconds."""
+
+    history_windows: int = 120
+    """How many recent windows to retain for variance / trend analysis
+    (default 120 × 0.25s = 30 seconds)."""
+
+    half_life_windows: float = 8.0
+    """Exponential decay half-life in windows for the temporal attention
+    aggregation. Default 8 × 0.25s = 2 seconds → recent two seconds carry
+    half the weight, older windows fade gracefully."""
+
+    weight_pattern_consistency: float = 0.40
+    weight_baseline_tension: float = 0.25
+    weight_sustained_capacity: float = 0.35
+
+    drain_rate_per_sec: float = 0.05
+    """Rate at which stamina drains in a normal working state. The actual
+    drain is `drain_rate × (1 + fatigue_evidence)` so high-fatigue
+    windows deplete faster."""
+
+    recovery_rate_per_sec: float = 0.10
+    """Rate at which stamina recovers in a resting state."""
+
+    rest_rms_threshold: float = 0.05
+    """Below this RMS the user is treated as resting (recovery, not drain)."""
+
+    state_focused_threshold: float = 60.0
+    state_depleted_threshold: float = 30.0
+
+    @property
+    def window_samples(self) -> int:
+        return max(1, int(self.window_size_sec * self.sample_rate_hz))