Metadata-Version: 2.4
Name: leanpeek
Version: 0.1.0
Summary: Turn a QuantConnect LEAN backtest result JSON into a one-line summary and a small report.
Author-email: Noah TaeHwan <noah.taehwan@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Noah-TaeHwan/leanpeek
Project-URL: Repository, https://github.com/Noah-TaeHwan/leanpeek
Keywords: quant,backtest,quantconnect,lean,reporting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: matplotlib>=3.6
Dynamic: license-file

<p align="center">
  <img src="assets/brand/leanpeek-logo.svg" width="300" alt="leanpeek">
</p>

<p align="center"><em>Lean backtest results, at a glance.</em></p>

<p align="center">
  <a href="https://github.com/Noah-TaeHwan/leanpeek/actions/workflows/ci.yml"><img src="https://github.com/Noah-TaeHwan/leanpeek/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/Noah-TaeHwan/leanpeek" alt="License: MIT"></a>
  <img src="https://img.shields.io/badge/python-3.9%20%E2%80%93%203.12-blue" alt="Python 3.9 through 3.12">
</p>

## What is leanpeek

`leanpeek` reads a [QuantConnect LEAN](https://github.com/QuantConnect/Lean)
backtest result JSON and turns it into **one human sentence** — plus a
terminal sparkline of the equity curve and drawdown, so you can see the shape
of the result before opening any file. If you want the details, it writes a
small report (`summary.csv`, `report.md`) and a chart (equity curve + drawdown,
with an optional ticker close overlay).

It was born as a bootcamp mini-project: the class ran a Samsung Electronics
Buy-and-Hold backtest on `quantconnect/lean` and the assignment was "turn the
results into something you'd actually use." `leanpeek` is that something — a
tiny, dependency-light CLI that makes the engine's output legible instead of a
215 KB JSON file.

## Quick start

```bash
pip install -e .          # or: pip install leanpeek (once published)

# Point it at a directory containing SamsungBuyAndHold.json (+ optional samsung.csv)
leanpeek -r sample

[local] 2024-01-01 ~ 2025-01-01: 1,000,000 -> 973,600 (net -2.640%), max drawdown 3.800%, Sharpe -3.919 | 1 order(s) (first: 2024-01-03 Buy 1 @ 79,600)
    equity  ▆▆▅▅▅▅▅▅▅▅▅▅▅▆▇▇▇▇▆▆▆▇▆▆▆▅▆▆▇▇▇███▇▇▆▆▆▆▆▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min 970,300 / max 1,008,200)
  drawdown  █▇▇▇▇▇▇▇▇▇▇▇▇▇████▇▆▆▇▇▇▆▆▆▇▇▇▇███▇▇▆▅▆▆▅▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min -3.8 / max 0.0)
reports -> leanpeek-out
```

(That exact output is pinned by `tests/test_sample.py`.) Add `--banner` for an
ASCII-art wordmark, `--ascii-plain` if your terminal can't render block glyphs,
and `--spark-width N` to control the sparkline length.

`leanpeek` writes three files into `leanpeek-out/` by default
(override with `-o`):

| output | contents |
|---|---|
| `summary.csv` | the LEAN `statistics` / `runtimeStatistics` flattened to a table |
| `report.md`   | the one-liner plus a Markdown table and data-usage notes |
| `lean_report.png` | equity curve + drawdown, with ticker close overlay when available |

```text
$ leanpeek -r sample
[local] 2024-01-01 ~ 2025-01-01: 1,000,000 -> 973,600 (net -2.640%), max drawdown 3.800%, Sharpe -3.919 | 1 order(s) (first: 2024-01-03 Buy 1 @ 79,600)
    equity  ▆▆▅▅▅▅▅▅▅▅▅▅▅▆▇▇▇▇▆▆▆▇▆▆▆▅▆▆▇▇▇███▇▇▆▆▆▆▆▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min 970,300 / max 1,008,200)
  drawdown  █▇▇▇▇▇▇▇▇▇▇▇▇▇████▇▆▆▇▇▇▆▆▆▇▇▇▇███▇▇▆▅▆▆▅▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min -3.8 / max 0.0)
reports -> leanpeek-out
```

```text
$ leanpeek -r sample --banner
 _                                  _
| | ___  __ _ _ __  _ __   ___  ___| | __
| |/ _ \/ _` | '_ \| '_ \ / _ \/ _ \ |/ /
| |  __/ (_| | | | | |_) |  __/  __/   <
|_|\___|\__,_|_| |_| .__/ \___|\___|_|\_\
                   |_|

[local] 2024-01-01 ~ 2025-01-01: 1,000,000 -> 973,600 (net -2.640%), max drawdown 3.800%, Sharpe -3.919 | 1 order(s) (first: 2024-01-03 Buy 1 @ 79,600)
    equity  ▆▆▅▅▅▅▅▅▅▅▅▅▅▆▇▇▇▇▆▆▆▇▆▆▆▅▆▆▇▇▇███▇▇▆▆▆▆▆▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min 970,300 / max 1,008,200)
  drawdown  █▇▇▇▇▇▇▇▇▇▇▇▇▇████▇▆▆▇▇▇▆▆▆▇▇▇▇███▇▇▆▅▆▆▅▅▄▃▃▃▃▂▂▂▂▂▁▁▂▂  (min -3.8 / max 0.0)
reports -> leanpeek-out
```

You can also run it as a module: `python -m leanpeek -r sample`.

## What it reads

A LEAN result JSON stores:

- equity curve under `charts.Strategy Equity.series.Equity.values`
  (`[timestamp, open, high, low, close]` rows),
- orders as a dict keyed by order id,
- metrics under `statistics` / `runtimeStatistics`.

`leanpeek` parses exactly that shape — no QuantConnect account, no data
provider, no network. Point it at any LEAN `-results` folder.

## Verification

Every number in this README is regenerated from the committed run in
[`sample/`](sample/) and pinned by
[`tests/test_sample.py`](tests/test_sample.py). CI runs `ruff` + `pytest` on
Python 3.10 and 3.12 — no network, no Docker. If a future LEAN version changes
the result format, the tests will notice before the README drifts.

## Limitations

- This is an **educational example**, not investment advice.
- The bundled sample strategy does **not** model KRX fees, dividends, trading
  calendar, or FX (as noted in the LEAN sample strategy), so treat the numbers
  as engine/format verification, not realistic performance.

## Acknowledgements

- The sample run was produced with the official
  [quantconnect/lean](https://hub.docker.com/r/quantconnect/lean) Docker image
  and the [QuantConnect LEAN engine](https://github.com/QuantConnect/Lean).

## License

MIT &copy; 2026 Noah TaeHwan. See [LICENSE](LICENSE).
