# AbleVLabs

*A public laboratory of Python tools, built to make difficult things easier and shared in the open.*

```bash
pip install ablevlabs
```

Three independent tools ship in the package, each importable on its own:

```python
from ablevlabs import kami   # machine learning for beginners
from ablevlabs import lana   # compare and rank anything
from ablevlabs import vita   # a reps-in-reserve training coach
```

| Reach for | when you want to |
|---|---|
| **kami** | go from a raw data file to a trained, explained model without getting lost in scikit-learn |
| **lana** | decide which option wins, or rank a whole field, by the criteria that matter to you |
| **vita** | know how many reps you have left, and plan your training sets around it |

---

## kami: machine learning that teaches as you go

`kami` wraps scikit-learn in a guided, beginner-first workflow. It catches the classic mistakes for you and explains them in plain English, and it teaches you what's happening as it happens, so you get smarter while you use it. It takes you the whole way from a raw file to real predictions.

```python
from ablevlabs import kami

df = kami.load("houses.csv")            # opens CSV, Excel, JSON, Parquet, and more
kami.look(df, target="price")           # understand the data before you model it
result = kami.train(df, target="price") # trains a model, handling the usual traps
kami.predict(result, new_houses)        # make predictions on new rows
```

What's inside:
- **Understand your data:** `look`, `report`, `audit`, and `recommend` size up a dataset and suggest what to predict.
- **Clean it:** `clean` tidies the common messes and explains each fix as it makes it.
- **Train and compare:** `train` builds one model, and `bakeoff` trains several and ranks them best first.
- **Trust it:** `feature_importance` and `plot_predictions` show what the model leaned on and how well it did.
- **Use it:** `predict` scores new data, and `whatif` shows how a prediction shifts as you change one input.
- **Charts in one line:** `bar`, `line`, `scatter`, `hist`, `pie`, `heatmap`, `quickplot`.
- **A built-in classroom:** `info`, `learn`, `models`, `roadmap`, and `translate` explain the concepts and the jargon as you go.

New to it? Run `kami.info()`.

---

## lana: compare and rank anything

`lana` (Logical Attribute Node Aligner) weighs records field by field, using the priorities *you* set, and tells you which one wins. Hand it two records for a head-to-head verdict, or a whole list for a ranked leaderboard. It works on anything with comparable fields: job candidates, products, model runs, vehicles, game characters.

```python
from ablevlabs import lana

a = {"name": "Zoro",  "power": 9100, "speed": 80}
b = {"name": "Sanji", "power": 8800, "speed": 95}

lana.show(lana.compare(a, b, priority={"power": 5, "speed": 3}))
```

Rank a whole field the same way:

```python
lana.show(lana.rank([a, b, c, d], priority={"power": 5, "speed": 3}))
```

What's inside:
- **Two modes:** `compare` for a head-to-head, `rank` for a leaderboard across many records.
- **Your priorities:** weight the fields that matter with `priority`, mark fields where smaller is better with `lower_better`, and smooth over mismatched key names with `aliases`.
- **Results are just data:** every result is a plain dict, easy to inspect and reuse.
- **Export anywhere:** `to_json`, `to_csv`, `to_markdown`, `to_df` (pandas), or `save()` straight to disk.

See it live at [ablevlabs.com/lana.html](https://ablevlabs.com/lana.html).

---

## vita: your reps-in-reserve training coach

`vita` (Vivanco Intelligent Training Assistant) answers the questions a lifter actually asks: how many reps do I have left, how many should I do, and what should today's sets look like? You calibrate a lift once from a couple of hard sets, and from then on `vita` estimates your reps in reserve on every set, tracks fatigue across the session, and prescribes what comes next. It runs on the Vivanco Proximity-to-Failure Model (VPFM).

```python
from ablevlabs import vita

bench = vita.calibrate(weight1=315, reps1=5, weight2=275, reps2=9, name="Bench")
w = vita.Workout(bench)
w.target_reps(weight=275, rir=2)                 # reps to leave 2 in reserve, right now
w.log_set(weight=275, reps=8)                    # log a set; get a coaching readout back
w.build_plan(weight=275, target_rir=2, sets=5)   # prescribe today's sets
```

What's inside:
- **Calibrate with confidence:** build a lift from your hard sets, and `vita` scores how much to trust it and flags any set that doesn't fit.
- **Coaching on every set:** reps in reserve and RPE, a plain-language label, and advice on what to do next.
- **Three ways to plan:** hold a target RIR, hold fixed reps, or run a top set with back-offs.
- **Fit it to you:** feed in your own logged sessions and `vita` fits the fatigue model to your data, validating against held-out sets.
- **Learn it fast:** `vita.help()` explains the ideas, and `vita.info()` lists every function in plain English.

---

## About AbleVLabs

AbleVLabs is my public laboratory. It's where I learn, experiment, build things, break them, fix them, and share whatever I work out along the way. Every project is one more step from total beginner toward the engineer I'm trying to become. I believe in open source and in learning out loud, because almost every tool I use exists thanks to someone who shared their knowledge for free. This is me paying that back. If something I build helps even one person learn a little faster than I did, then it already did its job.

---

## Requirements

Python 3.8+. Dependencies (`numpy`, `pandas`, `scikit-learn`, `matplotlib`) install automatically.

## License

MIT © AbleVLabs

## Links

- [ablevlabs.com](https://ablevlabs.com)
- [github.com/AbleVLabs](https://github.com/AbleVLabs)
- [PyPI: ablevlabs](https://pypi.org/project/ablevlabs/)