Metadata-Version: 2.4
Name: speedrun-cat
Version: 1.0.0
Summary: A terminal-based mental math trainer for CAT prep — fast, fun, zero dependencies.
Author: Hatim
License: MIT
Project-URL: Homepage, https://github.com/YOUR_USERNAME/speedrun
Project-URL: Repository, https://github.com/YOUR_USERNAME/speedrun
Project-URL: Issues, https://github.com/YOUR_USERNAME/speedrun/issues
Keywords: cat-exam,mental-math,mbaentrance,terminal,cli,study-tool
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🏃 SPEEDRUN — CAT Mental Math Trainer

A terminal-based mental math trainer built for CAT prep. Text-only,
fast, and designed to be finished in 15-20 minutes so it doesn't eat
into your syllabus/mock time — it's a daily habit, not a study block.

Free, open source, zero dependencies (pure Python standard library).

---

## Install

Requires **Python 3.8+**. Pick whichever feels easiest:

### Option 1 — one-line install (recommended, no git needed)

**Mac/Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/speedrun/main/install.sh | bash
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/YOUR_USERNAME/speedrun/main/install.ps1 | iex
```

This sets up [pipx](https://pypa.github.io/pipx/) (an isolated, standard way
to install Python CLI tools) and installs SPEEDRUN through it. Open a new
terminal afterwards and just run:
```bash
speedrun
```
That's it — the `speedrun` command now works from anywhere, no `cd`, no
`python` prefix needed.

### Option 2 — pip/pipx directly

If you already have pipx or pip:
```bash
pipx install speedrun-cat     # recommended
# or
pip install --user speedrun-cat
```
Then run `speedrun` from anywhere.

### Option 3 — clone the repo, no install at all

```bash
git clone https://github.com/YOUR_USERNAME/speedrun.git
cd speedrun
python3 speedrun.py
```
or double-click `run.sh` (Mac/Linux) / `run.bat` (Windows) inside the folder.

### Uninstalling

```bash
pipx uninstall speedrun-cat
# or, if you used plain pip:
pip uninstall speedrun-cat
```

---

## First launch

It asks **one question**: where to save your daily reports. Point it at
your Obsidian vault (or any folder) — that's the entire setup.

---

## How a session works

1. **Pick categories** — auto-continue the weekly rotation, choose your
   own, or skip and let the app decide (default: 5/day, cycling through
   all 19 over about a week so nothing goes stale).
2. **Pick a difficulty:**
   - **Tutorial** — warm up the basics (~0-35% CAT difficulty)
   - **Main Quest** — real CAT-pace calculations (~35-70%)
   - **Boss Fight** — full CAT-level speed & shortcuts (~70-100%)

   Difficulty ramps up as you move through each category's questions —
   you're never stuck grinding the same difficulty for 15 minutes, and
   never thrown into the deep end on question one.
3. **Work through each category**, then a final **Mixed Practice** round
   pulling randomly from everything you just covered.

**While answering:** type a number + Enter. Blank + Enter skips a
question. `q` + Enter ends the session early — whatever you completed
still gets saved and logged.

Session length is adjustable in Settings:
- **Quick** (~10 min): 4 categories × 4 Qs + 6 mixed
- **Standard** (~15-20 min, default): 5 categories × 6 Qs + 10 mixed
- **Deep** (~25-30 min): 6 categories × 8 Qs + 14 mixed

---

## The 19 categories

Addition, Subtraction, Multiplication, Division, Tables, Fractions,
Percentages, Ratios, Averages, Squares, Cubes, Square Roots, Cube Roots,
Decimals, BODMAS, Mixed Arithmetic, Approximation, Number Properties,
and CAT-Style Calculation (a grab-bag of classic CAT shortcuts —
×99/999, a²−b² tricks, compound %, etc).

Questions lean on real CAT-style shapes (`35% of 840 + 48`, `999 × 27`,
`48² − 47²`) rather than flat arithmetic — see `src/speedrun_cat/categories.py`.

---

## The fun layer

- **XP** — every correct answer earns XP (harder/faster = more). Shown
  live in the main menu next to your rank.
- **Ranks** — Rookie Recruit → Numbers Cadet → Sharp Shooter →
  Speedrunner → Calc Assassin → Mental Math Elite → CAT Crusher →
  99.99%iler, based on lifetime XP.
- **Combos** — 🔥 shows up once you chain 3+ correct answers in a row.
- **Streaks** — consecutive practice days, tracked on the dashboard.

None of this affects question difficulty or scoring fairness — it's
motivation on top, not a mechanic you need to think about.

---

## Markdown reports (Obsidian-ready)

One file per day: `2026-07-27 - Speedrun.md`, saved into the folder
you chose at setup. Multiple sessions the same day append to the same
file instead of creating new ones.

Deliberately short — a score line, a category breakdown, and a short
"missed" list for spaced review. No walls of stats you'll never reread.

```markdown
## Session 1 — 09:14 · Main Quest

**19/24** (79%) · ⏱ 1m 54s · ⚡ 366 XP · 🔥 best combo x4

Categories: Percentages, Squares, BODMAS, Division

By category: Percentages 67% (6) · Squares 83% (6) · BODMAS 83% (6) · Division 83% (6)

**Missed (worth another look):**
- 40% of 224 → you said **1089.6**, correct **89.6**
- 84² → you said **8056**, correct **7056**

**Slowest correct answer:** 76² (5.5s)
```

## Analytics dashboard (in-app)

Accessible from the main menu — no need to open any files: total
sessions/questions, overall accuracy, average response time,
current/longest streak, strongest & weakest category, most/least
practiced category, and last-7/30-day summaries.

---

## Where your data lives

- `~/.speedrun/config.json` — remembers which folder you chose.
- `<your folder>/.speedrun-data/analytics.json` — all your stats,
  streaks, and rotation state. Hidden so your Obsidian vault only shows
  clean `.md` files.
- `<your folder>/*.md` — your daily reports.

Delete `~/.speedrun/config.json` any time to re-run first-time setup
(your reports/analytics are untouched).

---

## Contributing / extending it

Everything is modular by design — see `src/speedrun_cat/`:

| File | Responsibility |
|---|---|
| `main.py` | Menus, dashboard, settings, orchestration |
| `session.py` | Runs one practice session |
| `categories.py` | All 19 question generators — **add a new category here** |
| `gamification.py` | Difficulty tiers, XP formula, rank ladder |
| `stats.py` | Long-term analytics |
| `markdown_report.py` | Daily `.md` report generation |
| `storage.py` / `config.py` | Persistence |
| `ui.py` | Terminal colors/menus/formatting |

To add a category: write one `gen_<name>(t)` function in `categories.py`
returning a `Question`, then add it to `CATEGORY_GENERATORS`. It's
automatically included in rotation, manual picking, and stats — nothing
else needs to change.

PRs welcome. This project is MIT-licensed — free to use, modify, and
redistribute.

## For maintainers: releasing a new version

1. Bump the version in `pyproject.toml` and `src/speedrun_cat/__init__.py`.
2. Push a Git tag / create a GitHub Release.
3. `.github/workflows/publish.yml` builds and publishes to PyPI
   automatically via [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
   (configure once in your PyPI project settings → no API tokens to manage).
