syntax-workout-core 0.2.0

Workout tree algebra — represent any physical workout as a recursive tree
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167

# syntax-workout-sdk

Workout tree algebra -- represent any physical workout as a recursive tree.

[![crates.io](https://img.shields.io/crates/v/syntax-workout-core.svg)](https://crates.io/crates/syntax-workout-core)
[![npm](https://img.shields.io/npm/v/@syntax-workout/sdk.svg)](https://www.npmjs.com/package/@syntax-workout/sdk)
[![PyPI](https://img.shields.io/pypi/v/syntax-workout-sdk.svg)](https://pypi.org/project/syntax-workout-sdk/)
[![CI](https://github.com/nicetomeetyu/syntax-workout-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/nicetomeetyu/syntax-workout-sdk/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](LICENSE-MIT)

## Install

**Rust**

```toml
[dependencies]
syntax-workout-core = "0.1"
```

**Node.js**

```sh
npm install @syntax-workout/sdk
```

**Python**

```sh
pip install syntax-workout-sdk
```

## Core concept

Every workout is a tree of `Node`s. Leaf nodes are individual sets; inner nodes group them into exercises, blocks, sessions, days, weeks, phases, and programs.

```
Program
  Week
    Day
      Session ("Upper Hypertrophy")
        Block (Sequential)           -- straight sets
          Exercise ("Bench Press")
            Set [100kg x 5]
            Set [100kg x 5]
        Block (Parallel)             -- superset
          Exercise ("DB Row")
            Set [30kg x 10]
          Exercise ("Lateral Raise")
            Set [12.5kg x 15]
        Block (Circuit {rounds: 3})  -- circuit
          Exercise ("Squat")
            Set [60kg x 15]
          Exercise ("Push-up")
            Set [20 reps]
          Exercise ("Plank")
            Set [60s]
```

Each `Node` carries a `kind`, a `payload`, optional `children`, and open-ended `metadata`.

## Quick example

**Rust** (builder API)

```rust
use syntax_workout_core::builder::*;
use syntax_workout_core::{ExecutionMode, Intensity};
use syntax_workout_core::measure::WeightUnit;

let workout = WorkoutBuilder::new("w1")
    .sport("strength")
    .date("2026-03-29")
    .root(session("Upper Hypertrophy", |s| {
        s.block(ExecutionMode::Parallel, |b| {
            b.name("Superset A")
             .rest(90.0)
             .exercise("DB Row", |e| {
                 e.set(vec![weight(30.0, WeightUnit::Kg), reps(10)], Some(rpe(8.0)));
             })
             .exercise("Incline Press", |e| {
                 e.set(vec![weight(25.0, WeightUnit::Kg), reps(12)], None);
             });
        });
    }))
    .build();

let json = serde_json::to_string_pretty(&workout).unwrap();
```

**Node.js** (parse + validate)

```js
import { readFileSync } from 'fs';
import { parseWorkout, validateWorkout, countSets } from '@syntax-workout/sdk';

const json = readFileSync('examples/strength/supersets.json', 'utf-8');

// Parse and round-trip through Rust types
const workout = JSON.parse(parseWorkout(json));
console.log(workout.sport); // "strength"

// Validate only (returns error strings, empty = valid)
const errors = validateWorkout(json);

// Count total sets
const sets = countSets(json);
```

**Python** (parse + validate)

```python
import syntax_workout_sdk

json_str = open("examples/strength/supersets.json").read()

# Parse into Python dict
workout = syntax_workout_sdk.parse_workout(json_str)
print(workout["sport"])  # "strength"

# Validate only
errors = syntax_workout_sdk.validate_workout(json_str)

# Count sets
count = syntax_workout_sdk.count_sets(json_str)
```

## ExecutionMode

Controls how children of a `Block` node are performed.

| Mode | Meaning | Example |
|------|---------|---------|
| `Sequential` | Finish all sets of exercise A, then B | Straight sets |
| `Parallel` | Alternate sets across exercises | Supersets, giant sets |
| `Circuit { rounds: N }` | Cycle through all exercises N times | Circuit training |
| `Custom(String)` | User-defined | AMRAP, EMOM |

## Measure variants

| Variant | Fields | Example |
|---------|--------|---------|
| `Reps` | `u32` | `Reps(10)` |
| `Weight` | `value: f64, unit: Kg\|Lbs` | `Weight { 80.0, Kg }` |
| `Distance` | `value: f64, unit: Meters\|Kilometers\|Miles` | `Distance { 5.0, Km }` |
| `Duration` | `seconds: f64` | `Duration { 180.0 }` |
| `Pace` | `per: DistanceUnit, seconds: f64` | `Pace { Km, 330.0 }` |
| `HeartRate` | `bpm: u32` | `HeartRate { 145 }` |
| `Calories` | `u32` | `Calories(350)` |
| `Custom` | `name: String, value: Value` | `Custom { "elevation", 150 }` |

## Intensity variants

| Variant | Fields | Example |
|---------|--------|---------|
| `PercentOfMax` | `f64` (0.0-1.0) | `PercentOfMax(0.80)` |
| `RPE` | `f64` (1-10) | `RPE(8.5)` |
| `RIR` | `u32` | `RIR(2)` |
| `Bodyweight` | -- | `Bodyweight` |
| `Custom` | `name: String, value: Value` | `Custom { "zone", 3 }` |

## Examples

See [`examples/`](examples/) for JSON workout files covering strength, endurance, and mixed modalities.

## License

MIT OR Apache-2.0