leanpeek

LEAN 백테스트 결과, 한눈에.
Lean backtest results, at a glance.

leanpeek은 뭐예요? / What is leanpeek

한국어

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

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

English

leanpeek reads a 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

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.)

[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

생성되는 파일 / What you get

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/에 커밋된 실제 백테스트 런에서 재생성되며, 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/ and pinned by 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 Docker 이미지와 QuantConnect LEAN 엔진으로 만들었습니다.

라이선스 / License

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