leanpeek

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

---

leanpeek은 뭐예요? / What is leanpeek

한국어

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

삼성전자 Buy & Hold 백테스트를 quantconnect/lean Docker 이미지로 실행하면서 시작했습니다. LEAN 엔진은 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 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

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

옵션	한국어	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) 백테스트를 실행하고 결과를 요약합니다.

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. Docker must be running; if it is not, leanpeek explains what to do.

생성되는 파일 / 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의 몫입니다. 전체 흐름은 이렇습니다.

[백테스트 실행]  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초 안에 결론이 나옵니다. 파일을 열지 않고도 기간, 시작/종료 잔고, 수익률, 최대낙폭, 샤프, 체결 주문을 읽고, 스파크라인으로 수익곡선이 우상향인지 하락인지 모양까지 확인합니다.

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/에 커밋된 실제 백테스트 런에서 재생성되며, 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 파일을 보세요.