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

# 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`)와 차트(순자산곡선 + 낙폭, 선택으로 티커 종가 오버레이)도 함께 만들어 줍니다.

삼성전자 Buy & Hold 백테스트를 `quantconnect/lean` Docker 이미지로 실행하면서 시작했습니다. LEAN 엔진은 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 began with a Samsung Electronics Buy-and-Hold backtest run on the `quantconnect/lean` Docker image. The engine leaves behind a 215 KB result JSON; leanpeek is a small CLI that makes it legible without opening the 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 |

## 백테스트 실행까지 (Docker) / Run a backtest (Docker)

한 명령으로 LEAN(Buy & Hold) 백테스트를 실행하고 결과를 요약합니다.

```bash
pip install leanpeek
leanpeek run                                # 기본: 005930.KS, 2024년
leanpeek run --ticker 005930.KS --start 2024-01-01 --end 2024-12-31
```

최초 실행 시 Docker 이미지(`leanpeek-runner:local`, `quantconnect/lean` 기반)를 빌드합니다(수 분, 진행 로그 출력). 결과는 `leanpeek-out/run-<시각>/`에 `BuyAndHold.json`·`orders.csv`·`summary.csv`·`report.md`·`lean_report.png`로 기록됩니다.

**English.** Run the built-in Buy & Hold backtest and summarize it in one command. The first run builds a local Docker image based on `quantconnect/lean` (may take a few minutes; progress is printed). Results land in `leanpeek-out/run-<timestamp>/`: `BuyAndHold.json`, `orders.csv`, `summary.csv`, `report.md`, `lean_report.png`, and `report.html`. Docker must be running; if it is not, leanpeek explains what to do.

## 결과를 웹으로 / Export to HTML

백테스트 요약을 **한 장의 self-contained HTML**로 내보냅니다. 차트·지표·스파크라인이 모두 파일 안에(base64) 들어가서, 이메일이나 노션에 붙여넣어도 그대로 보입니다. 네트워크·호스팅 불필요.

```bash
leanpeek export -r sample -o report.html   # 리더 결과를 HTML로
leanpeek run                                # run은 완료 시 report.html 자동 생성
```

**English.** Export a backtest summary as a **single self-contained HTML file**. The chart, metrics and sparkline are all embedded (base64), so the file renders anywhere with no network or hosting. `leanpeek run` also writes `report.html` into the result folder automatically.

## 생성되는 파일 / 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`처럼 모듈 실행도 가능합니다.

## 백테스트부터 결과까지 / From backtest to summary

**한국어.** leanpeek은 백테스트를 돌리지 않습니다. 백테스트는 QuantConnect LEAN 엔진(공식 `quantconnect/lean` Docker 이미지)이 하고, 그 결과를 받아 요약하는 게 leanpeek의 몫입니다. 전체 흐름은 이렇습니다.

```text
[백테스트 실행]  quantconnect/lean (LEAN 엔진)
       │  산출물: SamsungBuyAndHold.json · orders.csv · 로그
       ▼
[결과 폴더]      예: lean-results/
       │  leanpeek -r <결과 폴더>
       ▼
[요약]           한 줄 결론 + 스파크라인 + summary.csv / report.md / lean_report.png
```

LEAN 백테스트를 한 번 돌리면 보통 결과 폴더에 아래 파일들이 생깁니다. leanpeek은 그중 결과 JSON만 읽고 나머지는 건드리지 않습니다.

| 결과 파일 | 한국어 | English |
|---|---|---|
| `SamsungBuyAndHold.json` | 순자산곡선·주문·지표가 담긴 결과 JSON (leanpeek 입력) | the result JSON leanpeek reads |
| `orders.csv` | 체결된 주문 내역 | executed orders |
| 로그(`log.txt` 등) | 백테스트 실행 로그 | run logs |

**English.** leanpeek does not run backtests. QuantConnect LEAN (the official `quantconnect/lean` Docker image) does that; leanpeek reads what it leaves behind. Point `-r` at any folder that holds the result JSON and it summarizes it for you.

## 읽는 데이터 / 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.

## 사용자 시나리오와 UX / User journeys & UX

**한국어.** 세 가지 전형적인 쓰임새를 상상해 보세요.

**A. 방금 백테스트가 끝났다, 한눈에 보고 싶다**
결과 폴더만 지정하면 1초 안에 결론이 나옵니다. 파일을 열지 않고도 기간, 시작/종료 잔고, 수익률, 최대낙폭, 샤프, 체결 주문을 읽고, 스파크라인으로 수익곡선이 우상향인지 하락인지 모양까지 확인합니다.

```bash
leanpeek -r lean-results
```

설치는 `pip install leanpeek` 한 줄이 전부입니다.

**B. 전략이나 기간을 바꿔가며 비교한다**
백테스트 여러 개를 각자 폴더에 돌려두고 `leanpeek -r <폴더>`를 폴더마다 실행합니다. 결과는 `leanpeek-out/`에 쌓이고, `lean_report.png`나 `summary.csv`를 나란히 열어 수익률·낙폭·샤프를 비교할 수 있습니다.

**C. 결과를 기록하고 공유한다**
`report.md`와 `summary.csv`, `lean_report.png`가 파일로 남으므로 리포트를 저장하거나 다른 사람에게 그대로 건넬 수 있습니다. 모든 처리는 로컬에서 일어납니다.

사용자 경험 원칙은 세 가지입니다.

1. 한 명령, 한 화면. 설치 1줄, 실행 1줄, 출력 1화면.
2. 결론 먼저, 증거는 원할 때. 터미널엔 한 줄 요약, 상세는 파일로.
3. 가볍고 오프라인. 의존성은 `pandas`와 `matplotlib`뿐, 네트워크·계정 불필요.

**English.** Three typical use cases.

- **Just finished a backtest, want a quick look.** Point `leanpeek -r <folder>` at the results and get a one-line conclusion plus the equity/drawdown shape in about a second. Install is a single `pip install leanpeek`.
- **Comparing strategies or periods.** Run each backtest into its own folder, then run leanpeek per folder; outputs accumulate in `leanpeek-out/` so `summary.csv` or `lean_report.png` can be compared side by side.
- **Recording or sharing results.** `report.md`, `summary.csv` and `lean_report.png` are plain files you can keep or pass on. Everything is processed locally.

UX principles: one command, one screen; conclusion first, evidence on demand; lightweight and offline (only `pandas` and `matplotlib` as dependencies).

## 검증 / 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) 파일을 보세요.
