Metadata-Version: 2.4
Name: s2s-certify
Version: 1.8.0
Summary: Physics-certified motion data toolkit for Physical AI training
Author-email: Timur Davkarayev <timur.davkarayev@gmail.com>
License-Expression: BUSL-1.1
Project-URL: Homepage, https://github.com/timbo4u1/S2S
Project-URL: Repository, https://github.com/timbo4u1/S2S
Project-URL: Bug Tracker, https://github.com/timbo4u1/S2S/issues
Project-URL: Documentation, https://timbo4u1.github.io/S2S
Keywords: biomechanics,imu,motion-capture,physical-ai,robotics,prosthetics,sensor-certification,physics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ml
Requires-Dist: torch>=2.0; extra == "ml"
Requires-Dist: numpy>=1.24; extra == "ml"
Requires-Dist: scipy>=1.10; extra == "ml"
Requires-Dist: scikit-learn>=1.0; extra == "ml"
Requires-Dist: Pillow>=9.0; extra == "ml"
Requires-Dist: cryptography>=41.0; extra == "ml"
Provides-Extra: research
Requires-Dist: scipy>=1.10; extra == "research"
Requires-Dist: wfdb>=4.0; extra == "research"
Requires-Dist: matplotlib>=3.5; extra == "research"
Requires-Dist: seaborn>=0.12; extra == "research"
Provides-Extra: dashboard
Requires-Dist: streamlit>=1.30; extra == "dashboard"
Requires-Dist: numpy>=1.24; extra == "dashboard"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# S2S — Motion Data Quality Diagnostics & Audit

**S2S makes motion data quality measurable, explainable, and repeatable before that data is used to train a model.**

> **Using S2S on your data?** Open a [GitHub Discussion](https://github.com/timbo4u1/S2S/discussions) — I will personally help you integrate it with your dataset for free. Looking for the first 5 research partners.

[![PyPI](https://img.shields.io/pypi/v/s2s-certify)](https://pypi.org/project/s2s-certify/) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22912004.svg)](https://doi.org/10.5281/zenodo.22912004) [![License](https://img.shields.io/badge/License-BSL--1.1-blue)](LICENSE) [![python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml) [![dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](pyproject.toml) [![CI](https://github.com/timbo4u1/S2S/actions/workflows/ci.yml/badge.svg)](https://github.com/timbo4u1/S2S/actions/workflows/ci.yml)

```bash
## Demo — Real Human EMG → S2S Certified → Prosthetic Hand

[![S2S Demo](docs/s2s_demo.mp4)](docs/s2s_demo.mp4)

Watch: [docs/s2s_demo.mp4](docs/s2s_demo.mp4)

Real NinaPro DB5 EMG data → S2S 16-law physics certification → gesture classifier trained on GOLD/SILVER windows only → MuJoCo prosthetic hand (REST / FLEX power grasp / EXTEND open hand).

---

pip install s2s-certify
s2s-refinery --input /your/dataset --output report.csv
```

**Proven on real datasets:**

| Dataset | Windows | Usable | Rejected | Finding |
|---|---|---|---|---|
| NinaPro DB5 | 24,802 | 99% | 0% | Clean lab data — sensor_freeze 16% (Delsys hardware). No gyro — Law 16 skips. Confirmed valid v1.7.9. |
| PAMAP2 | 9,746 | 77% | 19% | Legacy certification summary (separate from classifier evaluation). Updated five-seed, 9-subject LOSO: three IMUs vs chest-only +4.79 pp fixed 12-class macro-F1. Physics-based chain filtering vs a matched-size random subset: +0.08 pp (exploratory 95% subject-bootstrap interval −0.30 to +0.50 pp); no downstream classification advantage demonstrated. |
| WESAD wrist | 200 | 95% | 4% | 32Hz structural limit — 86% SILVER expected |
| PTT-PPG | 371 | 100% | 0% | High quality walking data |

S2S audits motion sensor datasets and produces explainable, window-level diagnostic reports for supported checks such as sensor freeze, powerline interference, splice artifacts, and physically inconsistent recordings. Reports support review and decisions by data owners; they do not guarantee that filtering improves downstream model performance. In the five-seed, 9-subject PAMAP2 LOSO evaluation, chain filtering removed 23.8% of training windows. Against a matched random subset of equivalent size, physics-based selection showed no demonstrated downstream classification advantage (+0.08 pp; exploratory 95% subject-bootstrap interval −0.30 to +0.50 pp). Multi-sensor fusion independently contributed +4.79 pp macro-F1 versus chest-only input.

Run it on your dataset. Processing time and assessment coverage depend on the input format, sensor modalities, windowing, and enabled checks.

---





## Where S2S fits in a physical-AI pipeline

```
Human wears sensor
        |
        v
Raw IMU/EMG/PPG stream
        |
        v
+-----------------------------------+
|  S2S Layers 1-5  <- THIS REPO    |
|  L1: physics gate                 |
|  L2: biological origin            |
|  L3: semantic retrieval           |
|  L4: next action / gap fill       |
|  L5: visual scene understanding   |
+-----------------------------------+
        |
        v
Certified motion tokens (GOLD/SILVER + Ed25519 provenance)
        |
        v
[ Policy model training - outside S2S scope ]
  diffusion policy / ACT / OpenVLA
        |
        v
Robot / prosthetic actuator
        |
        v
+-----------------------------------+
|  S2S command-check prototype      |
|  measured latency in one test*    |
+-----------------------------------+
        |
        v
Physical world
```

S2S is a quality-assessment layer, not the policy model. It assigns S2S-defined tiers to supported sensor data and includes experimental command-check wrappers. These outputs are not independent accreditation or safety guarantees; a downstream model's behavior must be validated separately.

---

## Why this exists

Most motion datasets contain bad data — corrupted recordings, synthetic signals that violate physics, mislabeled actions. You cannot see it by looking at the numbers. Your model trains on it anyway.

S2S evaluates supported motion streams against biomechanical and signal-quality checks, such as Newton's Second Law, segment resonance, and rigid-body kinematics when the required inputs are present. Law 16 (innovation kurtosis) has been evaluated as a soft signal on coupled OU/Cholesky synthetic cases; it is not a universal synthetic-data detector, and biological rest windows can overlap with OU signals in kurtosis space. This validation is separate from the Level 4 PAMAP2 LOSO evaluation, which uses four kinematic-chain laws.

S2S does not replace existing AI systems. It adds quality checks for supported motion streams. The 16-law set is input-dependent: camera/video, VR/AR, or simulation frames do not automatically receive the same sensor-physics certification and require modality-specific checks.

For robotics and embodied AI pipelines, S2S provides separate checks for supported inputs: stream alignment where timestamps are available, physical consistency across assessable laws, Ed25519 provenance signing when configured, Hurst-exponent biological-origin screening, segment-level quality tiers, and a separate 2D wavelet/spectral synthetic-data screening experiment. These checks are not all enabled or assessed for every input, and they were not jointly evaluated in the Level 4 LOSO benchmark.

**v1.7.9 added:** Law 16 innovation kurtosis as a soft screening signal for the evaluated coupled OU/Cholesky cases. The three documented checks cover spatial (L9), temporal (L12), and distributional (L16) coherence. Available tests cover specific generators and scenarios; they do not establish that all possible synthetic generators will be detected. Current CI status is reported by the live badge above.


**Selected evaluation results across 8 datasets (separate experiments; metrics are not directly comparable):**

| Dataset | Hz | Sensors | Result |
|---|---|---|---|
| UCI HAR | 50Hz | IMU | −5.83% F1 vs clean baseline (artificial 35% corruption — filtering reduces training set more than noise; not a valid S2S use case) |
| PAMAP2 | 100Hz | IMU ×3 | Five-seed, 9-subject LOSO: multi-sensor vs chest-only +4.79 pp fixed 12-class macro-F1. Physics-based chain filtering vs matched-size random subset: +0.08 pp (exploratory 95% subject-bootstrap interval −0.30 to +0.50 pp); no demonstrated downstream advantage. |
| WISDM 2019 | 20Hz | IMU | +1.74% F1 vs corrupted baseline |
| WESAD | 700Hz | IMU + BVP | +3.1% F1 stress classification |
| RoboTurk Open-X | 15Hz | Robot arm | 97.7% pass rate (v1.7.9, 216 episodes, 1143 windows). Note: v1.5.0 showed 78.1% pass under 8-law set — not directly comparable due to law set change |
| NinaPro DB5 | 2000Hz | Forearm EMG+IMU | 9,552 windows certified, Law 1 EMG validated 78% |
| OPPORTUNITY | 30Hz | Body IMU ×7 | 25.7% rejection rate found with real gyro |
| PhysioNet PTT-PPG | 500Hz | Wrist PPG+IMU | 1,164 windows certified |

---

## Real-time performance

Certified on real NinaPro DB5 data (2000Hz, 500-sample windows):

| Metric | Value |
|---|---|
| Observed mean latency | 1.99ms in this specific test configuration (v1.7.9, 16 laws, 256-sample window, 2000Hz); not a worst-case guarantee |
| Window duration | 250ms |
| CPU overhead | 1.1% |
| Compared with window interval | 89× faster than the 250ms window duration in this benchmark; not a worst-case guarantee |
| Safety certification | Not safety-certified; separate hardware-specific validation is required |

Laws run on IMU-only data (no gyro hardware):
- resonance_frequency: RUNS (conf=26)
- rigid_body_kinematics: RUNS (conf=45, zero gyro = low coupling)
- jerk_bounds: RUNS (conf=92) ← primary detector at 2000Hz
- imu_internal_consistency: RUNS (conf=45)
- newton_second_law: skipped (needs EMG)
- ballistocardiography: skipped (needs PPG)
- joule_heating: skipped (needs thermal)

With a full sensor stack (IMU + EMG + PPG + gyro), all 16 checks can run, subject to implementation-specific input requirements. This does not imply that every law passes or that the system is safety-certified.


**Interpreting certification status:** Each rule is `PASS`, `FAIL`, or `NOT_ASSESSED`. Missing modalities, insufficient samples, unsupported sample rates, and internal check errors are `NOT_ASSESSED`—never `PASS`—and do not contribute a neutral score. Results report `assessment_status`, `tier_scope`, assessed/not-assessed counts, and per-law statuses. A GOLD/SILVER/BRONZE tier describes only the checks that were assessed when `tier_scope=ASSESSED_CHECKS_ONLY`; it is not a claim that unavailable sensor modalities were validated.

## Platform Support

S2S runs on any platform Python supports:

| Platform | Status | Notes |
|---|---|---|
| Linux (Ubuntu/Debian) | ✅ Tested | Primary platform, Docker/Alpine supported |
| macOS | ✅ Tested | Intel and Apple Silicon |
| Windows | ✅ Compatible | Pure Python core, no native dependencies |
| Raspberry Pi | ✅ Tested | Zero-dependency core runs on 1GB RAM |
| Alpine Linux (Docker) | ✅ Tested | Minimal container deployment |

Core physics laws require zero dependencies.
NumPy is optional (automatic fast-path when available).

## Install

```bash
pip install s2s-certify
```

**30-second test — zero extra dependencies:**
```python
from s2s_standard_v1_3.s2s_physics_v1_3 import PhysicsEngine
import random
engine = PhysicsEngine()
acc = [[random.gauss(0,2), random.gauss(0,2), 9.81+random.gauss(0,0.3)] for _ in range(256)]
ts  = [int(i*5e6) for i in range(256)]  # 200 Hz
r   = engine.certify({"timestamps_ns": ts, "accel": acc, "gyro": [[0,0,0]]*256})
print(r["tier"], r["score"])  # → GOLD  87
```

```bash
pip install "s2s-certify[ml]"        # with PyTorch — enables Layers 4 and 5
pip install "s2s-certify[dashboard]" # with Streamlit
```

Layer 5 visual understanding also requires:
```bash
pip install git+https://github.com/openai/CLIP.git
pip install sentence-transformers
```

---

## Full 7-layer demo output

Run on a real DROID robot manipulation episode:

```bash
python3.9 s2s_demo.py --droid ~/droid_data/droid_100/1.0.0
```

```
════════════════════════════════════════════════════════════
  S2S — Full Chain Demo  (v1.7.9)
  7 Layers: Physics → Biology → Motion → Visual
════════════════════════════════════════════════════════════

  S2SPipeline(segment=forearm,
    Layer1(Physics) + Layer2(BioSession) + Layer4a(NextAction) +
    Layer4b(GapFill) + Layer4c(Intent) + Layer3(Retrieval) + Layer5(CLIP))

[INPUT] Instruction: 'Put the marker inside the silver pot'
        Video frame: 31,964 bytes JPEG

  ───────────────────────────────────────────────────────
  LAYER 1 — Physics Certification
  ───────────────────────────────────────────────────────
  tier                   SILVER
  score                  66/100
  source_type            HIL_BIOLOGICAL
  laws_passed            ['resonance_frequency', 'rigid_body_kinematics',
                          'jerk_bounds', 'imu_internal_consistency', ...]
  laws_failed            []

  ───────────────────────────────────────────────────────
  LAYER 2 — Biological Origin (Session)
  ───────────────────────────────────────────────────────
  biological_grade       NOT_BIOLOGICAL
  hurst                  0.4917       (synthetic test signal, <0.70)
  bfs_score              0.7468
  n_windows              9
  recommendation         REJECT
  note                   HUMAN grade requires real session data (NinaPro r=0.929)

  ───────────────────────────────────────────────────────
  LAYER 3 — Semantic Motion Retrieval
  ───────────────────────────────────────────────────────
  match_1                1.0000  Put the marker inside the silver pot
  match_2                0.7268  Put the marker inside the blue cup
  match_3                0.6658  Take the marker from the bowl and put it on the table

  ───────────────────────────────────────────────────────
  LAYER 4a — Next Action Prediction
  ───────────────────────────────────────────────────────
  next_motion_8dim       [-0.846, 1.354, 2.997, -0.908, 1.326, 2.946, -0.143, -0.400]
  note                   pos_xyz + vel_xyz + jerk_rms + smoothness

  ───────────────────────────────────────────────────────
  LAYER 4b — Gap Filling (3 intermediates)
  ───────────────────────────────────────────────────────
  t=1/4                  [5.717, 4.739, 11.777, 0.345]
  t=2/4                  [5.888, 4.883, 11.695, 0.384]
  t=3/4                  [5.956, 4.943, 11.316, 0.406]

  ───────────────────────────────────────────────────────
  LAYER 4c — Intent Recognition
  ───────────────────────────────────────────────────────
  intent                 Put the marker inside the silver pot
  confidence             1.0000
  method                 text query override

  ───────────────────────────────────────────────────────
  LAYER 5 — Visual Understanding (CLIP)
  ───────────────────────────────────────────────────────
  clip_sim               0.2253
  visual_input           31,964 byte JPEG
  instruction            Put the marker inside the silver pot

════════════════════════════════════════════════════════════
  CHAIN SUMMARY
════════════════════════════════════════════════════════════
  Physics tier:       SILVER (score 66/100)
  Biological grade:   NOT_BIOLOGICAL (Hurst 0.4917, synthetic test signal)
  Top intent:         Put the marker inside the silver pot (1.0)
  Next motion:        ✓ predicted
  Gap fill:           ✓ 3 intermediates
  Scene similarity:   0.2253

  Full chain: sensor → physics → biology → intent → motion → visual
════════════════════════════════════════════════════════════
```

### Layer 5 — Visual discrimination stress test

Same scene, three different instructions — proves the system is not random:

| Instruction | Similarity | vs correct |
|---|---|---|
| "Put the marker inside the silver pot" *(correct)* | 0.2253 | baseline |
| "pick up the blue cup and place on shelf" *(wrong object)* | 0.2108 | −7% |
| "walking down the street" *(completely irrelevant)* | 0.1327 | −41% |

An irrelevant command scores 41% lower on the same scene. Zero-shot, no fine-tuning.

---

## Reproducible benchmark

### Synthetic-only smoke run

The default command runs generated cases only. It does not load NinaPro, PAMAP2, or WESAD.

```bash
git clone https://github.com/timbo4u1/S2S
cd S2S
python3 run_benchmark.py
```

### Dataset-backed run

Provide paths to datasets you are authorized to use:

```bash
python3 run_benchmark.py --all \
  --ninapro "$HOME/ninapro_db5" \
  --pamap2 "$HOME/S2S_data/pamap2" \
  --wesad "$HOME/wesad_data/WESAD"
```

The runner adds five Gaussian-noise cases, seven hard-negative perturbations, and five coupled-OU cases. Dataset-backed totals depend on the available files and usable windows, so do not compare aggregate pass rates when the case sets differ. Its `pass` metric means the output tier met the case-specific expected-tier rule; it is not a detection-accuracy or sensitivity estimate. In the latest CI smoke run, 16/17 cases met their expected-tier rules with zero execution errors. Law 16 flagged all 3 standard OU cases but only 1 of 2 aggressive OU cases; one aggressive case remained SILVER and was not flagged.

### Historical reference result (v1.7.8)

[experiments/s2s_reference_benchmark.json](experiments/s2s_reference_benchmark.json) records a fixed 36-case v1.7.8 set: 21 real-data windows, 3 spike-injected windows, 5 IID Gaussian windows, and 7 hard negatives. It predates the current runner's five coupled-OU cases and is not the expected output for the current runner.

The historical spike-injection checks allowed either BRONZE or REJECTED; they did not require every case to be BRONZE. The 36-case result is a fixed test set, not evidence of universal detection or validation across arbitrary data.

Updated PAMAP2 LOSO (9 subjects, five seeds 42–46; fixed 12-class macro-F1): multi-sensor fusion vs chest-only was +4.79 pp. The primary matched-control comparison, physics-filtered data vs an equivalent-size random subset, was +0.08 pp with an exploratory 95% subject-bootstrap interval of −0.30 to +0.50 pp. The interval crosses zero and seed-level effects had mixed signs; this experiment does not demonstrate downstream classification benefit from physics-based filtering. Chain filtering removed 23.8% of training windows in this evaluation. The interval is exploratory, based on nine held-out subjects, and is not formal significance testing.

Full reproducible five-seed analysis: [experiments/results_level4_pamap2_loso_matched_analysis.json](experiments/results_level4_pamap2_loso_matched_analysis.json). Individual runs and the corrected seed-42 rerun are preserved separately.

See the [S2S value validation protocol](docs/S2S_value_validation_protocol.md) for the evaluation design and follow-up validation of known-corruption detection and independent replication.

## Status & Roadmap

The repository contains prototype components for a 7-layer pipeline; validation maturity varies by layer and input modality.
Next development direction depends on what real users need.

If you are using S2S on your data — even just experimenting —
open a [GitHub Discussion](https://github.com/timbo4u1/S2S/discussions) or email **s2s.physical@proton.me**.
One sentence about your use case helps more than you think.

**Completed in v1.8.0:**
- Content-based delimiter detection for comma, semicolon and tab files
- Numeric-aware header detection preserving scientific notation and NaN/Inf values
- Explicit sensor-unit normalization and SI conversion for supported units
- Sensor-column validation: cardinality, type, bounds, duplicate axes, cross-sensor overlap rejection
- PAMAP2 six-mapping regression coverage for all hand, chest and ankle accelerometer/gyroscope mappings
- Explicit gyro availability states: complete, partial, absent, invalid, unit_unknown
- LeRobot adapter invalid gyro state alignment with column adapter
- Preservation of sensor provenance and no fabricated gyro measurements

**Completed in v1.7.9:**
- Law 16: Innovation Kurtosis — soft screening signal for evaluated coupled OU / Cholesky cases; not a universal synthetic-data detector
- Calibrated on real PAMAP2 data (6,547 windows, 3 subjects): soft signal, not hard reject
  (rest-state biological windows overlap with OU in kurtosis space, p5=0.10 < threshold 0.63)
- Law 16 penalizes OU score and flags detection — combined with dual coherence firewall
- Fixed cross_axis_cohesion duplicate registration (was running 12× per window)
- Fixed version strings: CLI 1.4.0→1.7.9, tool v1_5→v1_9, docstring 7→16 laws
- NaN guard added to check_innovation_kurtosis
- Test status is tracked by the live CI badge; the suite has changed since v1.7.9.
- docs/S2S_pipeline_guide.md — full architecture reference

**Completed in v1.7.8:**
- Batch Refinery (`s2s-refinery` CLI) — process entire dataset folders, output tier/score/law CSV report
- Duplicate file deduplication — handles nested folder structures

**Completed in v1.7.7:**
- Resonance frequency hz-gate — skipped at <40Hz (Nyquist insufficient for tremor detection)
- WESAD audit findings documented — ADC unit correction, 86% SILVER expected at 32Hz

**Completed in v1.7.6:**
- Law 14: Powerline Interference — FFT spike detection at 50/60Hz, soft flag
- Law 15: Intra-Window Splice — sustained half-window level shift > 8 m/s², soft flag
- cross_axis_cohesion ×6 duplication bug fixed

**Completed in v1.7.5:**
- Laws 9–12: Cross-Axis Cohesion, Pointwise Jerk, Spectral Flatness, Temporal Autocorrelation — dual coherence firewall
- Law 13: Sensor Freeze (state-conditioned soft flag) — rest vs active threshold, 36/36 benchmark maintained
- Sample Entropy (Layer 2) — biological complexity detector, Richman & Moorman 2000
- Intent registry — 8 semantic motion intents (gentle/careful/normal/fast/ballistic/amputee/elderly/rehab)
- Visualizer — matplotlib physics audit plots (plot_certification, plot_session)
- 60% latency reduction — np.partition replaces np.percentile in check_jerk (7.5ms → 2.95ms)
- VLASafetyWrapper — real-time physics gate for VLA models (RT-2, Pi-0)
- session_report() — HIL recording quality timeline with re-record recommendations
- audit_report() — human-readable law explanations with hardware fix suggestions

**Completed in v1.7.0:**
- Law 8: Inter-window continuity — catches timestamp regression and session splices
- 2D Physical Firewall: Wavelet CV + Spectral Entropy — catches synthetic data that fools FFT
- Zero-config certify_file() — auto-detects Hz, units, and columns from any sensor file
- Field-ready: error recovery, streaming for large files, any sensor mounting angle

**Planned — depends on user needs:**
- Layer 6: LLM semantic reasoning (jerk limits from natural language)
- CLIP fine-tuning on DROID (0.23 → 0.6+ scene similarity)
- Amputee-specific physics thresholds ([Issue #5](https://github.com/timbo4u1/S2S/issues/5))
- Kinematic chain validation (Denavit-Hartenberg, needs multi-segment IMU dataset)

---

## Architecture

```
Layer 1  Physics Certification    16 laws (12 hard + 4 soft flags), GOLD/SILVER/BRONZE/REJECTED
Layer 2  Biological Origin        Hurst H≥0.70 + Sample Entropy 0.35-0.95, HUMAN/NOT_BIOLOGICAL
Layer 3  Motion Retrieval         text → certified motion, 11,246 windows, 6 datasets
Layer 4a Next Action Prediction   Transformer, mean r=0.929, 21,896 training pairs
Layer 4b Gap Filling              +5.5% over linear interpolation, Flash & Hogan 1985
Layer 4c Intent Recognition       top-5 75.9%, 71 labels, sentence-transformers
Layer 5  Visual Understanding     CLIP ViT-B/32, frame-synced at 15Hz
```

---

## Layer 1 — Physics Certification

16 biomechanical laws validated at runtime (12 hard + 4 soft flags — Laws 13-16):

| Law | Equation | Requires | What it catches |
|---|---|---|---|
| Newton's Second Law | F = ma | IMU + EMG | EMG force must lead acceleration by ~75ms |
| Segment Resonance | ω = √(K/I) | IMU | Physiological tremor 8–12Hz for forearm |
| Rigid Body Kinematics | a = α×r + ω²×r | IMU + gyro | Gyro and accel must co-vary on a rigid body |
| Ballistocardiography | F = ρQv | IMU + PPG | Heartbeat recoil visible in wrist IMU at PPG rate |
| Joule Heating | Q = 0.75×P×t | EMG + thermal | EMG bursts must produce thermal elevation |
| Motor Control Jerk | d³x/dt³ ≤ 500 m/s³ | IMU | Human motion limit (Flash & Hogan 1985) |
| IMU Internal Consistency | Var(accel) ~ Var(gyro) | IMU + gyro | Independent generators produce zero coupling |
| Inter-window Continuity | \|Δaccel\| ≤ V_max/dt | IMU | Catches timestamp regression and session splices between windows |
| Cross-Axis Cohesion | max(r_xy,r_yz,r_xz) > 0.115 | IMU | Gaussian noise has independent axes — no biomechanical coupling |
| Pointwise Jerk | \|a_i − a_{i−1}\| / dt ≤ 10000 m/s³ | IMU | Sub-millisecond spikes impossible for human tissue |
| Spectral Flatness | geo_mean(PSD) / arith_mean(PSD) < 0.54 | IMU | Gaussian noise has uniform spectrum — human motion has peaks |
| Temporal Autocorrelation | ACF[lag=1] > 0.20 | IMU | No temporal coherence = iid noise, not biological motor control |
| Sensor Freeze (soft) | consecutive identical > 10 (active) / 25 (rest) | IMU | Hardware fault vs legitimate static posture — state-conditioned |
| Powerline (soft) | FFT spike > 8× local mean at 50/60Hz | IMU | Mains interference in sensor cables — battery-powered sensors clean |
| Splice (soft) | half-window mean diff > 8 m/s² | IMU | Session concatenation artifact — sustained level shift mid-window |
| Innovation Kurtosis (soft) | excess_kurtosis(AR1_residuals) > 0.63 | IMU + gyro | Soft flag evaluated on coupled OU / Cholesky cases, not proof of synthetic origin. Rest-state biological windows overlap with OU in kurtosis space (PAMAP2 p5=0.10). |

Missing or insufficient inputs are marked `NOT_ASSESSED`; they are excluded from `laws_passed`, `laws_failed`, and the quality-score average. The output includes per-law `PASS` / `FAIL` / `NOT_ASSESSED`, assessment coverage, and `assessment_status`. A tier describes assessed checks only when `tier_scope` is `ASSESSED_CHECKS_ONLY`; it must not be interpreted as a complete assessment of unavailable sensor modalities.

### Body segment parameters

| Segment | I (kg·m²) | K (N·m/rad) | Tremor band (Hz) |
|---|---|---|---|
| `forearm` | 0.020 | 1.5 | 8–12 |
| `upper_arm` | 0.065 | 2.5 | 5–9 |
| `hand` | 0.004 | 0.3 | 10–16 |
| `finger` | 0.0003 | 0.05 | 15–25 |
| `head` | 0.020 | 1.2 | 3–8 |
| `walking` | 10.0 | 50.0 | 1–3 |

### Tier system

| Tier | Condition |
|---|---|
| GOLD | score ≥ 75 AND passed ≥ n_laws − 1 |
| SILVER | score ≥ 55 |
| BRONZE | score ≥ 35 |
| REJECTED | >30% laws failed OR score < 35 OR dual coherence failure (no spatial+temporal structure) |

---

## What passes each layer — complete picture

The table below summarizes specific test scenarios only; it is not a guarantee for arbitrary synthetic generators or biological sessions.

| Signal type | L1 Physics | L2 Biology | L3 Semantic | L5 CLIP |
|---|---|---|---|---|
| Gaussian noise | FAIL | — | — | — |
| Pure sine wave | FAIL | — | — | — |
| Coupled OU (standard; 3 built-in cases) | Law 16 soft flag: 3/3 flagged in current smoke run | — | — | — |
| Coupled OU (aggressive; 2 built-in cases) | Law 16 soft flag: 1/2 flagged in current smoke run; one remained SILVER | — | — | — |
| Frozen signal (zero gyro) | PASS | FAIL (H≈1) | — | — |
| Replay wrong label | PASS | PASS | FAIL (soft) | FAIL (if video) |
| Replay correct label | PASS | PASS | PASS | PASS |

In the test scenarios above, only the correctly labelled real biological example passed all listed layers. This is a result for those test cases, not a universal guarantee about all possible inputs.
That is the intended behavior — the system certifies quality, not identity.

---

## Layer 2 — Biological Origin

```python
pe = PhysicsEngine()
for window in session_windows:
    pe.certify(imu_raw=window, segment="forearm")

verdict = pe.certify_session()
print(verdict["biological_grade"])   # HUMAN / LOW_BIOLOGICAL_FIDELITY / NOT_BIOLOGICAL
print(verdict["hurst"])              # ≥0.70 = biological motor control
print(verdict["recommendation"])     # ACCEPT / REVIEW / REJECT
```

---

## Layer 3 — Motion Retrieval

```python
pipe = S2SPipeline(segment="forearm")
matches = pipe.query_intent("pick up the cup", top_k=3)
# [("pick object", 0.484), ("drinking", 0.411), ("Put the marker inside the blue cup", 0.379)]
```

---

## Layer 4 — Action Sequencing

### 4a — Next action prediction (mean r=0.929)

```python
result = pipe.certify(imu_raw=window)
print(result["next_motion"])  # 8-dim: pos_xyz + vel_xyz + jerk_rms + smoothness
```

### 4b — Gap filling (+5.5% over linear interpolation)

```python
gaps = pipe.fill_gap(start_features, end_features, n_steps=3)
```

| Position | Neural r | Linear r | Improvement |
|---|---|---|---|
| t=0.33 | 0.944 | 0.889 | +0.055 |
| t=0.50 | 0.960 | 0.909 | +0.051 |
| t=0.67 | 0.945 | 0.889 | +0.056 |

### 4c — Intent recognition (top-5 accuracy 75.9%)

```python
result = pipe.certify(imu_raw=window, instruction="pick up cup")
print(result["intent"])       # "pick object"
print(result["intent_sim"])   # 0.887
```

---

## Layer 5 — Visual Understanding

Frame-synchronized CLIP ViT-B/32 at 15Hz. Each motion window pairs with the video frame at that exact timestep. Accepts any visual input: camera, VR render, AR overlay, simulation frame.

```python
result = pipe.certify(
    imu_raw=window,
    instruction="Put the marker inside the silver pot",
    video_frame=jpeg_bytes,
)
print(result["clip_sim"])   # 0.2253
```

---

## All 6 sensor certifiers

```python
from s2s_standard_v1_3 import PhysicsEngine
result = PhysicsEngine().certify(imu_raw={...}, segment="forearm")

from s2s_standard_v1_3.s2s_emg_certify_v1_3 import EMGStreamCertifier
ec   = EMGStreamCertifier(n_channels=8, sampling_hz=1000.0)
cert = ec.push_frame(ts_ns, [ch0..ch7])

from s2s_standard_v1_3.s2s_ppg_certify_v1_3 import PPGStreamCertifier
pc   = PPGStreamCertifier(n_channels=2, sampling_hz=100.0)
cert = pc.push_frame(ts_ns, [red, ir])

from s2s_standard_v1_3.s2s_lidar_certify_v1_3 import LiDARStreamCertifier
lc   = LiDARStreamCertifier(mode='scalar')
cert = lc.push_frame(ts_ns, [distance_m])

from s2s_standard_v1_3.s2s_thermal_certify_v1_3 import ThermalStreamCertifier
tc   = ThermalStreamCertifier(frame_width=32, frame_height=24)
cert = tc.push_frame(ts_ns, flat_pixels)

from s2s_standard_v1_3.s2s_fusion_v1_3 import FusionCertifier
fc = FusionCertifier(device_id="glove_v2")
fc.add_imu_cert(imu_cert)
fc.add_emg_cert(emg_cert)
result = fc.certify()
print(result["human_in_loop_score"])   # 0–100
```

---

## Cryptographic signing

```python
from s2s_standard_v1_3.s2s_signing_v1_3 import CertSigner, CertVerifier

signer, verifier = CertSigner.generate()
signer.save_keypair("keys/device_001")
signed = signer.sign_cert(cert_dict)
ok, reason = verifier.verify_cert(signed)
```

---

## Device registry

```python
from s2s_standard_v1_3.s2s_registry_v1_3 import DeviceRegistry

reg = DeviceRegistry("registry.json")
reg.register(
    device_id="glove_v2_001",
    sensor_profile="imu_9dof",
    owner="you@example.com",
    expected_jitter_ns=4500.0,
    public_key_pem=signer.export_public_pem(),
    trust_tier="PROVISIONAL",
)
ok, reason, device = reg.validate_cert(cert_dict)
reg.promote("glove_v2_001")
```

---

## REST API

```bash
python3 -m s2s_standard_v1_3.s2s_api_v1_3 --port 8080
```

| Method | Path | Description |
|---|---|---|
| POST | `/certify/imu` | Batch IMU certification |
| POST | `/certify/emg` | Batch EMG certification |
| POST | `/certify/lidar` | Batch LiDAR |
| POST | `/certify/thermal` | Batch thermal frames |
| POST | `/certify/ppg` | Batch PPG certification |
| POST | `/certify/fusion` | Fuse 2–5 stream certs |
| POST | `/stream/frame` | Push frame to persistent session |
| GET | `/health` | Health + active sessions |

---

## LeRobot / Hugging Face Integration

Certify any LeRobot dataset episode directly:

```python
from s2s_standard_v1_3.adapters.lerobot import certify_lerobot_dataframe
import pandas as pd

df = pd.read_parquet('episode_000000.parquet')
result = certify_lerobot_dataframe(df, hz=30.0, segment='forearm')

print(result['pass_rate'])     # 0.847
print(result['summary_tier'])  # SILVER
print(result['rejected'])      # windows with physics violations
```

For datasets with real IMU/acceleration streams. Standard simulation datasets
(PushT, ALOHA) use joint positions — pass `accel_cols` explicitly for those.
See [adapters/lerobot.py](s2s_standard_v1_3/adapters/lerobot.py) for details.

## Real-Time Command-Check Prototype (Experimental)

Example stream-checking wrapper. A 2.8ms latency was observed in one 2000Hz configuration; this is not a worst-case execution-time guarantee or a safety certification.

```python
from s2s_standard_v1_3 import RealTimeSafetyGate

gate = RealTimeSafetyGate(segment="forearm", strikes_required=3)

for ts_ns, accel, gyro in sensor_stream:
    is_safe, reason, cert = gate.push(ts_ns, accel, gyro)
    if not is_safe:
        print(f"UNSAFE: {reason}")
        # halt pipeline / alert operator / log event
```

States:
- `SAFE` — SILVER or GOLD, data is physically trustworthy
- `DEGRADED` — BRONZE, quality reduced but not dangerous
- `UNSAFE` — 3 consecutive REJECTED windows, action required

Latency: 2.95ms per window at 2000Hz (1.1% CPU overhead).
Three-strike logic prevents false triggers from single noise samples.

## Roadmap — Layer 6: Semantic Reasoning

The current 7 layers certify that motion is physically real and visually consistent. Layer 6 adds semantic reasoning — bridging natural language intent to physics constraints:

```
User says:   "Feed the baby"
Layer 5:     sees spoon, bowl, baby face
Layer 6:     translates to physics constraints:
               jerk ≤ 50 m/s³  (gentle)
               speed ≤ 0.3 m/s
               trajectory toward face
             Layer 1 validates before robot executes
```

Requires LLM cross-attention to physical trajectory space. Planned after first external users.

---

## Quick CLI

```bash
s2s-certify yourfile.csv
s2s-certify yourfile.csv --output report.json --segment forearm

# Dataset quality report — entire folder
s2s-refinery --input /path/to/dataset --output report.csv --segment forearm
```

**Zero-config Python API — auto-detects columns, Hz, and units:**

```python
from s2s_standard_v1_3.adapters.column_detect import certify_file

# Works on any CSV or space-delimited sensor file
# No column names needed — detects accel/gyro from data statistics
result = certify_file("your_sensor_data.csv", segment="forearm")

print(result["tier"])             # SILVER
print(result["pass_rate"])        # 0.93
print(result["detected_hz"])      # 30.3 (auto-detected from timestamps)
print(result["detected_columns"]) # {"accel": [2,5,17], "gyro": [1,16,39]}
```

Auto-detect is best for unknown datasets without documentation.
For documented datasets, specify columns explicitly for highest accuracy.

---

## VLA Command-Check Wrapper (Experimental)

Prototype wrapper for evaluating configured checks on outputs from a VLA model (RT-2, Pi-0, etc.). It is not a certified safety controller and must not be the sole protection between a policy model and hardware actuators:

```python
from s2s_standard_v1_3.adapters.vla_wrapper import VLASafetyWrapper

wrapper = VLASafetyWrapper(hz=10.0, segment="forearm", window_size=8)

# For each VLA output command (position or acceleration):
for step in robot_episode:
    decision = wrapper.check_position(step["xyz"])  # or check_acceleration()
    
    if decision["action"] == "EXECUTE":
        robot.move(step)
    elif decision["action"] == "EXECUTE_WITH_CAUTION":
        robot.move_slow(step)
    else:  # HOLD
        robot.stop()
        print(f"Physics violation: {decision['reason']}")

# States: SAFE / DEGRADED / UNSAFE
# Three-strike logic prevents false triggers
```

On the tested NYU Robot dataset subset (erasing-board, pouring, and hanging tasks), all 14 episodes received SILVER under S2S's configured checks. This result describes those episodes only; it does not establish that all robot motion is safe or within validated human biomechanical limits.

---

## Human-readable audit report

```python
from s2s_standard_v1_3.s2s_physics_v1_3 import PhysicsEngine, audit_report

engine = PhysicsEngine()
result = engine.certify(imu_raw=window, segment="forearm")
report = audit_report(result)

print(report["verdict"])         # "SILVER — Good data quality"
print(report["recommendation"])  # "Apply 12Hz low-pass filter"
for issue in report["issues"]:
    print(f"  ⚠️  {issue['law']}: {issue['message']}")
    print(f"     Fix: {issue['fix']}")
```

---

## HIL Session Quality Report

For recording sessions with human operators:

```python
engine = PhysicsEngine()

# Certify windows during recording
for window in live_stream:
    engine.certify(imu_raw=window, segment="forearm")

# Get session quality report
report = engine.session_report(session_id="take_001", segment="forearm")

print(report["verdict"])          # "EXCELLENT — ready for robot training."
print(report["pass_rate"])        # 0.94
print(report["tier_counts"])      # {"GOLD": 12, "SILVER": 82, ...}
for rec in report["recommendations"]:
    print(f"  • {rec}")           # actionable fix suggestions
# Problem segments to re-record:
for seg in report["problem_segments"]:
    print(f"  Re-record: {seg['start_s']:.1f}s-{seg['end_s']:.1f}s ({seg['tier']})")
```

---

## Semantic Motion Intents

Map natural language motion descriptions to physics constraints:

```python
from s2s_standard_v1_3.intent_registry import (
    get_intent_constraints, list_intents, intent_for_jerk
)

# Get physics constraints for an intent
c = get_intent_constraints("gentle")
print(c["jerk_limit"])    # 50.0 m/s³
print(c["description"])   # "Fragile items, surgery, elderly care"

# List all intents
for name, desc in list_intents().items():
    print(f"{name}: {desc}")

# Auto-classify by observed jerk
intent = intent_for_jerk(45.0)   # "gentle"
intent = intent_for_jerk(300.0)  # "normal"
```

Available intents: `gentle` (50 m/s³), `careful` (100), `normal` (500), `fast` (1200), `ballistic` (5000), `amputee` (350), `elderly` (150), `rehabilitation` (80)

Population-specific intents (amputee/elderly/rehabilitation) address [Issue #5](https://github.com/timbo4u1/S2S/issues/5).

---

## Physics Audit Visualization

```python
from s2s_standard_v1_3.visualizer import plot_certification, plot_session

# Single window audit plot
plot_certification(imu_raw, result,
    title="Forearm IMU Physics Audit",
    save_path="audit.png")

# Session quality timeline
report = engine.session_report(session_id="take_001")
plot_session(report["quality_timeline"],
    session_id="Recording Session 1",
    save_path="session.png")
```

Tier colors: GOLD=#FFD700, SILVER=#C0C0C0, BRONZE=#CD7F32, REJECTED=#FF4444

---

## Live demos

[→ IMU Demo](https://timbo4u1.github.io/S2S/) · [→ Physical AI Demo](https://timbo4u1.github.io/S2S/demo_physical_ai.html) · [→ Live API](https://s2s-65sy.onrender.com/health) · [→ Paper PDF](docs/paper/S2S_Paper_v5.pdf) · [DOI: 10.5281/zenodo.22912004](https://doi.org/10.5281/zenodo.22912004)

---

## Support this project

S2S is free for research. If it saved you time or helped your pipeline:

**Crypto donations (any amount):**
| Network | Address |
|---|---|
| USDT TRC20 | `TXRSTigHsk5QgAiuN2JJyByRuXmawVxdBP` |
| ETH ERC20  | `0x6E7B9d022DC49bfc21C3011E15A0bF2868ec9c26` |
| SOL        | `4gVZxGec3GefmkME4UXpn1CmrzvsiHguASqArxnSjSHY` |

Or open a [GitHub Discussion](https://github.com/timbo4u1/S2S/discussions) — feedback is worth more than money at this stage.

## License

BSL-1.1 — free for research and non-commercial use. Apache 2.0 from 2028-01-01.
