Metadata-Version: 2.4
Name: leanpeek
Version: 0.1.1
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

# leanpeek

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

<p align="center"><em>LEAN 백테스트 결과, 한눈에.</em><br><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="https://pypi.org/project/leanpeek/"><img src="https://img.shields.io/pypi/v/leanpeek" alt="PyPI"></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>

---

## leanpeek은 뭐예요? / What is leanpeek

**한국어**

`leanpeek`은 [QuantConnect LEAN](https://github.com/QuantConnect/Lean) 백테스트 결과 JSON을 읽어 한 줄 요약과 터미널 스파크라인(순자산곡선, 낙폭)을 보여주는 CLI 도구입니다. 원하면 작은 리포트(`summary.csv`, `report.md`)와 차트(순자산곡선 + 낙폭, 선택으로 티커 종가 오버레이)도 함께 만들어 줍니다.

이 프로젝트는 AI 퀀트 부트캠프 미니프로젝트에서 시작했습니다. 수업에서 삼성전자 Buy & Hold 전략을 `quantconnect/lean` Docker 이미지로 백테스트한 뒤 "백테스트 결과 데이터를 어떻게 활용해 볼래?"라는 과제가 나왔는데, 이 도구가 그 답입니다. 215KB짜리 결과 JSON을 열어보지 않고도 백테스트가 어떻게 돌아갔는지 금방 알 수 있습니다.

**English**

`leanpeek` reads a [QuantConnect LEAN](https://github.com/QuantConnect/Lean) backtest result JSON and prints one human sentence plus a terminal sparkline of the equity curve and drawdown. On request it also writes a small report (`summary.csv`, `report.md`) and a chart (equity + drawdown, optional ticker close overlay).

It started as a bootcamp mini-project. After running a Samsung Electronics Buy-and-Hold backtest on the `quantconnect/lean` Docker image, the assignment was "turn the results into something you'd actually use." This is that something: a tiny CLI that makes the engine's output legible instead of a 215 KB JSON file.

## 빠른 시작 / Quick Start

```bash
pip install leanpeek      # PyPI에서 설치 / install from PyPI
# 소스에서 직접 설치하려면 / or from source: pip install -e .

# 백테스트 결과가 담긴 폴더를 지정하세요
# Point it at a directory containing SamsungBuyAndHold.json (+ optional samsung.csv)
leanpeek -r sample
```

출력 예시, 아래 값은 테스트로 고정한 값입니다. (The output below is pinned by tests.)

```text
[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
```

**옵션 / Options**

| 옵션 | 한국어 | English |
|---|---|---|
| `--banner` | ASCII 아트 워드마크 출력 | print the ASCII-art wordmark |
| `--ascii-plain` | 블록 글자 대신 순수 ASCII 스파크라인 | use pure-ASCII sparklines |
| `--spark-width N` | 스파크라인 길이 조절 (기본 56) | sparkline width in characters |
| `--ticker-csv <파일>` | 가격 오버레이용 OHLCV CSV 지정 | OHLCV CSV for the price overlay |
| `-o <폴더>` | 리포트 산출물 폴더 지정 (기본 `leanpeek-out`) | output directory |

## 생성되는 파일 / What you get

| 파일 | 한국어 | English |
|---|---|---|
| `summary.csv` | LEAN `statistics`/`runtimeStatistics`를 표로 정리 | LEAN metrics flattened to a table |
| `report.md` | 한 줄 요약 + 지표 표 + 데이터 노트 | the one-liner, a metrics table, notes |
| `lean_report.png` | 순자산곡선 + 낙폭 차트 (종가 오버레이 포함 가능) | equity + drawdown chart (optional close overlay) |

`python -m leanpeek -r sample`처럼 모듈 실행도 가능합니다.

## 읽는 데이터 / What it reads

LEAN 결과 JSON은 이렇게 생겼습니다.

- 순자산곡선: `charts.Strategy Equity.series.Equity.values` (`[timestamp, open, high, low, close]`)
- 주문: order id를 키로 하는 dict
- 지표: `statistics` / `runtimeStatistics`

`leanpeek`은 위 구조만 파싱합니다. QuantConnect 계정이나 데이터 제공자, 네트워크가 필요 없습니다. 어떤 LEAN `-results` 폴더든 가리키면 됩니다.

**English.** A LEAN result JSON stores the equity curve under `charts.Strategy Equity.series.Equity.values` (`[timestamp, open, high, low, close]` rows), orders as a dict keyed by order id, and metrics under `statistics` / `runtimeStatistics`. leanpeek parses exactly that shape. No QuantConnect account, no data provider, no network.

## 검증 / Verification

**한국어.** 이 README에 적힌 숫자는 모두 [`sample/`](sample/)에 커밋된 실제 백테스트 런에서 재생성되며, [`tests/test_sample.py`](tests/test_sample.py)가 그 값을 고정합니다. CI는 Python 3.10과 3.12에서 `ruff`와 `pytest`를 돌립니다. 네트워크도 Docker도 필요 없습니다. README에 적힌 숫자가 지어낸 게 아니라 실제 실행 결과라는 걸 테스트가 보장합니다.

**English.** 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 notice before the README drifts.

## 제약사항 / Limitations

- 교육용 예제이며 투자 조언이 아닙니다. This is an educational example, not investment advice.
- 이 샘플 전략은 KRX 수수료, 배당, 거래일, 환율을 모델링하지 않습니다 (LEAN 샘플 전략과 동일). 숫자는 실제 성과가 아니라 엔진과 포맷을 검증하는 용도로 보세요.
- The bundled sample strategy does not model KRX fees, dividends, calendar, or FX. Treat the numbers as engine/format verification, not realistic performance.

## 감사의 글 / Acknowledgements

샘플 런은 공식 [quantconnect/lean](https://hub.docker.com/r/quantconnect/lean) Docker 이미지와 [QuantConnect LEAN 엔진](https://github.com/QuantConnect/Lean)으로 만들었습니다.

## 라이선스 / License

MIT © 2026 Noah TaeHwan. 자세한 내용은 [LICENSE](LICENSE) 파일을 보세요.
