[Русский](README.ru.md)

# F1 Telemetry Analyzer

Turns raw F1 22 lap telemetry into compact Markdown reports you can paste into an LLM for analysis. A full raw lap is ~1M tokens; these reports are 1–35k.

```bash
# from the tool/ folder
python -m telemetry technique ../zandvoort_P_L7_74.074_ferrari.csv
# -> ../reports/zandvoort_P_L7_74.074_ferrari_technique.md   (~34k tokens)
```

Or just double-click `run-gui.bat` and click **Generate report**.

## Install

- Python 3.10+ (uses only the standard library — no `pip install`).
- Tk is required for the GUI; it ships with the standard Python installer on Windows/macOS. The CLI works without it.

Download or clone the repository. Keep your telemetry CSVs in the parent folder of `tool/` (see [folder layout](#folder-layout)).

## What it does

Five modes. Four produce reports, one renames files.

| Mode | Input | Use it to analyse |
|------|-------|-------------------|
| `technique` | one lap | **how** you drive — braking points, apex speeds, throttle application, lockups, resource cost |
| `setup` | one lap | **what** is set — balance (US/OS), tyre temps, brakes, suspension rake & roll |
| `compare` | two+ laps | **where** one lap is faster — per-corner and cumulative delta |
| `race` | a folder of laps | the whole race — pace, stint degradation, tyre wear, ERS per lap |
| `rename` | files/folder | insert the lap number into each filename (`..._74.074_...` → `..._L7_74.074_...`) |

Reports include a legend explaining every column, so the LLM understands the data without extra prompting. Ready-made analysis prompts live in [`prompts/`](prompts/) — one per mode.

### Folder layout

The program lives in `tool/`; your telemetry sits one level up, output lands next to it:

```
Telemetry/
  zandvoort_P_L7_74.074_ferrari.csv   <- raw laps here
  races/
    Zandvoort_Race_2026/              <- one folder per race (for `race` mode)
  reports/                            <- generated reports land here
  tool/                               <- this repository
    telemetry/
    prompts/
    run-gui.bat
```

## Handy things

**GUI** — double-click `run-gui.bat` (or `run-gui.pyw` for no console window, or run `python -m telemetry gui`). Pick a mode, browse to the file/folder, click Generate. The **Rename unprocessed** button adds lap numbers to files that don't have them yet and leaves the rest alone.

**CLI** — from the `tool/` folder:

```bash
python -m telemetry technique ../lap.csv
python -m telemetry setup     ../lap.csv
python -m telemetry compare   ../lap_a.csv ../lap_b.csv
python -m telemetry race      ../races/Zandvoort_Race_2026
python -m telemetry rename    ../races/Zandvoort_Race_2026   # or individual files
```

Every report run prints the output path and a token estimate:

```
C:\...\Telemetry\reports\lap_technique.md
~33834 tokens (budget 60k)
```

**Rename only touches unprocessed files.** A file is "processed" once its name contains an `L<number>` token, so re-running rename is safe and idempotent.

## Input format

F1 22 UDP telemetry exported to CSV (tested with [F1Laps](https://www.f1laps.com)). UTF-8, ~1800 rows per lap (≈29 Hz), 108 channels. One file = one lap. For `race` mode, drop all of a race's lap files into one folder.

## For developers

Pure-stdlib Python. Pipeline: `parser` → `segments` (+ `corner_metrics`) → `resample` → `report_*`. See [ARCHITECTURE.md](ARCHITECTURE.md).

```bash
cd tool
python -m pytest -q        # run the test suite
python -m telemetry gui    # launch the GUI
```

Adding a mode: drop a `telemetry/report_<mode>.py` exposing `generate(...) -> (abs_path, tokens)` and wire one line into `telemetry/__main__.py`. The parser, corner detection, adaptive trace, and shared report blocks are reused.

## Credits

Built for analysing personal F1 22 hotlaps. Telemetry export format from [F1Laps](https://www.f1laps.com).

## License

MIT — see [LICENSE](LICENSE).