Metadata-Version: 2.4
Name: kaiserlift
Version: 0.1.103
Summary: Science-based progressive overload system for weightlifting and running with Pareto optimization
Author-email: Douglas Kaiser <douglastkaiser@gmail.com>
License: MIT
Project-URL: Homepage, https://www.douglastkaiser.com/projects/#workoutPlanner
Project-URL: Documentation, https://github.com/douglastkaiser/kaiserlift#readme
Project-URL: Repository, https://github.com/douglastkaiser/kaiserlift
Project-URL: Bug Tracker, https://github.com/douglastkaiser/kaiserlift/issues
Keywords: fitness,weightlifting,progressive-overload,workout-optimization,running,pareto,1rm,strength-training,data-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Utilities
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: plotly
Requires-Dist: ipython
Provides-Extra: server
Requires-Dist: fastapi; extra == "server"
Requires-Dist: uvicorn; extra == "server"
Requires-Dist: python-multipart; extra == "server"
Requires-Dist: httpx; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Dynamic: license-file

# 🏋️ KaiserLift

[![PyPI version](https://badge.fury.io/py/kaiserlift.svg)](https://pypi.org/project/kaiserlift/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**A smarter way to choose your next workout: data-driven progressive overload**

🎯 **Never guess your next workout again** — KaiserLift analyzes your training history and tells you exactly which exercise, weight, and rep range will give you the easiest PR.

## ✨ Quick Start

### Installation

```bash
pip install kaiserlift
```

Or with [uv](https://docs.astral.sh/uv/) (recommended):

```bash
uv pip install kaiserlift
```

### Run the Web Interface

```bash
pip install "kaiserlift[server]"
kaiserlift-cli
```

Then open http://localhost:8000 in your browser and upload your FitNotes CSV export.

### Use as a Python Library

```python
from kaiserlift import pipeline

# Generate interactive HTML with workout recommendations
html = pipeline(["your_fitnotes_export.csv"])
with open("workout_plan.html", "w") as f:
    f.write(html)
```

### CSV Data Format

Your CSV should follow the FitNotes export format:

```csv
Date,Exercise,Category,Weight,Reps
2022-09-14,Flat Barbell Bench Press,Chest,45.0,10
2022-09-14,Dumbbell Curl,Biceps,35.0,10
```

## Why keep doing 10 rep sets? Are you pushing in a smart way?

The core idea I’m exploring is simple: I want a science-based system for determining what’s the best workout to do next if your goal is muscle growth. The foundation of this is progressive overload—the principle that muscles grow when you consistently challenge them beyond what they’re used to.

One of the most effective ways to apply progressive overload is by taking sets to failure. But doing that intelligently requires knowing what you’ve done before. If you have a record of your best sets on a given exercise, you can deliberately aim to push past those PRs. That history becomes your benchmark.

![Rawdata Curl Pulldown](images/RawDataCurlPulldownBicep.png "Rawdata Curl Pulldown")

Now, there’s another dimension to this: rep range adaptation. If you always train for, say, 10 reps, your muscles can get used to that rep range—even if you’re still pushing for PRs. Switching things up and going for, say, 20-rep maxes (even with lighter weight) can stimulate growth by forcing the muscle to adapt to new challenges. Then, when you go back to 10 reps, you might find you’ve blown through a plateau.

To make this system more precise, I propose using a one-rep max (1RM) equivalence formula—a way of mapping rep and weight combinations onto a single curve. It gives you a way to compare different PRs across rep ranges. Using that, you can identify which rep range you’re weakest in—meaning, which PR has the lowest 1RM equivalent. That’s where your next opportunity lies.

![Curl Pulldown with Pareto](images/CurlPulldownwithPareto.png "Curl Pulldown with Pareto")

For the 1 rep max we use [`The Epley Formula`](https://en.wikipedia.org/wiki/One-repetition_maximum#cite_ref-7):
$$
\text{estimated\_1rm} = \text{weight} \times \left(1 + \frac{\text{reps}}{30.0}\right)
$$

## Here's how to operationalize it:

1. Collect your full workout history for a given exercise—every weight and rep combo you’ve done.
2. Calculate the Pareto front of that data. This is the set of “non-dominated” performances: the heaviest weights at each rep range that can’t be beaten in both weight and reps at the same time.
3. For each point on the Pareto front, compute the 1RM equivalent using a decay-style formula.
4. Identify the Pareto front point with the lowest 1RM equivalent—that’s your weakest spot.
5. Now, generate a “next step” PR target: a new set that just barely beats that weakest point, by the smallest reasonable margin (e.g., +1 rep or +5 lbs). That becomes your next workout goal.

This method gives you a structured, data-driven way to chase the easiest possible PR—which is still a PR. That keeps you progressing without burning out.

You can extend this concept across exercises too. Let’s say it’s biceps day. Instead of defaulting to the same curl variation you always do, you can rotate in a bicep exercise you haven’t done recently in order to assure a new PR. This introduces variability, which is another powerful way to drive adaptation while still targeting the same muscle group.

![Curl Pulldown with Targets](images/CurlPulldownwithTargets.png "Curl Pulldown with Targets")

The end goal here is simple: use your data to intelligently apply progressive overload, break through plateaus, and train more effectively—with zero guesswork.

To this end I also made an HTML page that can organize these in a text searchable way and can be accessed from my phone at the gym. This table of taget sets can be ordered by 1RPM and so easilly parsed.

![Curl Pulldown Example - HTML](images/curlpulldown_html.png "Curl Pulldown Example - HTML")

## Advanced Usage

### Development

Set up a local environment with [uv](https://docs.astral.sh/uv/):

```
uv venv
uv sync --extra dev

# or, with pip:
pip install ".[dev]"
```

Run the full test suite (includes benchmarks via `pytest-benchmark`):

```
uv run pytest
```

Before committing, run the pre-commit hooks locally to mirror CI and avoid
formatting failures:

```
uvx pre-commit run --all-files
```

This installs the pinned `ruff-format` version and rewrites files if needed, so
rerun the command until it reports no changes.

Import data and run the pareto calculations:
```
import glob

from kaiserlift import (
    process_csv_files,
    highest_weight_per_rep,
    df_next_pareto,
)
csv_files = glob.glob("*.csv")
df = process_csv_files(csv_files)
df_pareto = highest_weight_per_rep(df)
df_targets = df_next_pareto(df_pareto)
```

Plotting the data:
```
from kaiserlift import plot_df

# Plot recorded sets
fig = plot_df(df, Exercise="Dumbbell Curl")
fig.write_image("build/Dumbbell_Curl_Raw.png")  # Requires the optional kaleido package

# Plot the Pareto front
fig = plot_df(df_pareto=df_pareto, Exercise="Dumbbell Curl")
fig.write_image("build/Dumbbell_Curl_Pareto.png")

# View with pareto and targets (the green x's)
fig = plot_df(df_pareto=df_pareto, df_targets=df_targets, Exercise="Dumbbell Curl")
fig.write_image("build/Dumbbell_Curl_Pareto_and_Targets.png")
```

Generate views:
```
from kaiserlift import (
    print_oldest_exercise,
    gen_html_viewer,
)

# Console print out with optional args
output_lines = print_oldest_exercise(df, n_cat=2, n_exercises_per_cat=2, n_target_sets_per_exercises=2)
with open("your_workout_summary.txt", "w") as f:
    f.writelines(output_lines)

# Print in HTML format for ease of use
full_html = gen_html_viewer(df)
with open("your_interactive_table.html", "w", encoding="utf-8") as f:
    f.write(full_html)

# Console print of the HTML
from IPython.display import display, HTML
display(HTML(full_html))
```

### Example HTML generation in CI

An example dataset and helper script live in `tests/example_use`. You can
generate the interactive HTML table locally with:

```
python tests/example_use/generate_example_html.py
```

The "Generate example HTML" job in the CI workflow runs the same script. When
run on the main branch, the generated pages are deployed to GitHub Pages:
- Landing page: `index.html`
- Lifting demo: `lifting/index.html`
- Running demo: `running/index.html`

The HTML is also available as a downloadable artifact for all branches.

### Graph-first dashboards

The lifting dashboard opens with an exercise selected and its interactive graph
above the target table. A star marks the proposed target with the lowest estimated
1RM; select a target marker or table row to inspect its weight and reps. The
recommendation panel follows your selection. Formula and chart explanations are
available under **How to read this graph**.

Running dashboards also show performance graphs before the target table. Both
views share responsive styling. When using the FastAPI server, open `/lifting/`
or `/running/` for sample dashboards. Static exports use the same chart
initializer, including after importing a lifting CSV or restoring cached results.

### Neo-retro training labs

The homepage, lifting lab, and running lab share a minimal early-web design:
numbered navigation, a page directory, bold headings, square instrument panels,
and a target register. Charts use the same paper, ink, cobalt, and green palette;
recorded performances and proposed targets keep distinct marker shapes.

Each plot has **Reset view** and **Save plot** controls. **Import data** lives
below the target register and is also linked from the page directory and homepage.
The browser importer supports both lifting and running exports, keeps their saved
histories separate, and preserves the current graphs when an import fails.
Clearing saved data returns to the example performance map. The static homepage
and FastAPI homepage use the same renderer; the server homepage also offers direct
CSV upload forms.
