krx-quant-core 0.1.1__py3-none-any.whl

krx_quant_core/__init__.py

@@ -0,0 +1,8 @@
+"""krx-quant-core — 한국 주식 퀀트 공통 코어.
+
+scalp-it(스캘핑)·daytrade-it(데이트레이딩)·swing-it(스윙 리서치)이 공유하는
+시장 규칙·비용·주문 가드·리스크·체결 시뮬레이션·검증 통계를 한곳에 둔다.
+전략 로직은 여기에 두지 않는다.
+"""
+
+__version__ = "0.1.1"

krx_quant_core/backtest/__init__.py

@@ -0,0 +1,36 @@
+"""백테스트 부품 — 호가 충격·지정가 체결 판정·트레이드 원장/성과지표·횡단면 시뮬레이션.
+
+엔진(이벤트 루프)은 여기 없다. 루프는 소비자마다 다르지만(틱 스캘핑·일봉 데이트레이딩·
+월간 리밸런스), 그 루프가 부르는 "체결됐나/얼마에/순손익이 얼마고 성과가 어떤가" 는
+세 레포가 같은 답을 내야 한다.
+"""
+
+from .crosssectional import rank_ic, rank_tilt_backtest, staggered_tranche_backtest
+from .fills import EPS, FILL_BASES, FillBasis, limit_buy_filled, limit_sell_filled
+from .ledger import PerformanceMetrics, Trade, TradeResult, apply_costs, performance_metrics
+from .orderbook import Level, liquidity_size_multiplier, roundtrip_bp, sweep_vwap
+from .panels import adv_panel, forward_returns, lookup_panel, panel_pivot
+
+__all__ = [
+    "EPS",
+    "FILL_BASES",
+    "FillBasis",
+    "Level",
+    "PerformanceMetrics",
+    "Trade",
+    "TradeResult",
+    "adv_panel",
+    "apply_costs",
+    "forward_returns",
+    "limit_buy_filled",
+    "limit_sell_filled",
+    "liquidity_size_multiplier",
+    "lookup_panel",
+    "panel_pivot",
+    "performance_metrics",
+    "rank_ic",
+    "rank_tilt_backtest",
+    "roundtrip_bp",
+    "staggered_tranche_backtest",
+    "sweep_vwap",
+]

krx_quant_core/backtest/crosssectional.py

@@ -0,0 +1,299 @@
+"""횡단면 순위 틸트 시뮬레이션 — 정기 리밸런스 + 측정 회전율 비용.
+
+swing-it ``engine/sim_crosssectional.py`` 를 **수치 동일**로 옮겼다(루프·기본값 그대로).
+원래 PEAD 전략에서 뽑아낸 회계(``t+1`` 진입, ADV 하한, 회전율 비용, 대차 비용, 롱온리
+초과수익)라, 다른 횡단면 실험이 그걸 다시 유도하지 않고 재사용하게 하려는 것이다.
+
+모든 입력은 ``code × date`` numpy 패널이고 ``dates`` 는 열 라벨 목록이다(반환 ``periods``
+프레임의 ``date`` 열에 그대로 실린다). DataFrame → 패널 변환은 :mod:`.panels` 참고.
+
+기본값(``start_index=130``·``adv_floor`` 등)은 swing-it 연구 수치에 고정돼 있다 —
+바꾸면 swing-it 의 발표 수치가 조용히 달라지므로 그대로 둔다.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..stats.metrics import newey_west_t, summarize_periods
+
+__all__ = ["rank_ic", "rank_tilt_backtest", "staggered_tranche_backtest"]
+
+
+def _trailing_adv(V: np.ndarray, nD: int, adv_window: int, like: np.ndarray) -> np.ndarray:
+    adv = np.full_like(like, np.nan)
+    for j in range(adv_window, nD):
+        adv[:, j] = np.nanmean(V[:, j - adv_window:j], axis=1)
+    return adv
+
+
+def rank_tilt_backtest(
+    close: np.ndarray,
+    trade_value: np.ndarray,
+    signal: np.ndarray,
+    dates: list,
+    *,
+    horizon: int = 40,
+    adv_floor: float = 5000.0,
+    adv_window: int = 20,
+    cost_one_way: float = 0.0023,
+    min_names: int = 30,
+    start_index: int = 130,
+    fresh_days: int = 0,
+    long_only: bool = False,
+    borrow_cost_annual: float = 0.0,
+    top_n: int = 0,
+    age: np.ndarray | None = None,
+) -> tuple[pd.DataFrame, dict]:
+    """순위 가중 달러중립(또는 롱온리 초과수익) 북, 측정 비용 차감.
+
+    ``horizon`` 거래일마다 리밸런스한다. ``t`` 시점 신호로 ``t+1`` 종가 진입(같은 종가
+    look-ahead 방지), ``t+1+horizon`` 종가 청산. ADV 는 ``t`` 직전 ``adv_window`` 일
+    평균(당일 제외).
+
+    Args:
+        close: ``code × date`` 가격 패널(상류에서 abs).
+        trade_value: ``code × date`` 거래대금 패널(``adv_floor`` 와 같은 단위).
+        signal: ``code × date`` 신호 패널.
+        dates: 패널 열에 맞춘 날짜 라벨.
+        long_only: 참이면 상위 틸트(또는 ``top_n`` 동일가중) 롱북의 **적격 유니버스 대비
+            초과수익**. 공매도가 막힌 경우의 구현 가능한 형태.
+        borrow_cost_annual: 달러중립일 때 숏 총액에 물리는 연 대차비용.
+        age: ``code × date`` 공시 경과일 패널; ``fresh_days>0`` 일 때만 본다.
+            ``None`` → 전부 NaN(신선도 게이트 없음).
+
+    Returns:
+        ``(periods, summary)`` — periods 열은 ``date, gross, turnover, net``,
+        summary 는 :func:`~krx_quant_core.stats.metrics.summarize_periods` 결과.
+    """
+    C = close
+    V = trade_value
+    yoy = signal
+    if age is None:
+        age = np.full_like(yoy, np.nan)
+    nD = len(dates)
+
+    adv = _trailing_adv(V, nD, adv_window, C)
+
+    def fwd(t: int, h: int) -> np.ndarray:
+        return C[:, t + h] / C[:, t] - 1.0 if t + h < nD else np.full(C.shape[0], np.nan)
+
+    rows: list[dict] = []
+    prev_w = np.zeros(C.shape[0])
+    t = start_index
+    while t < nD - horizon - 1:
+        sig = yoy[:, t].copy()
+        if fresh_days > 0:
+            sig = np.where(age[:, t] <= fresh_days, sig, np.nan)
+        ok = np.isfinite(sig)
+        ret = fwd(t + 1, horizon)  # t+1 진입 — 같은 종가 look-ahead 방지
+        ok &= np.isfinite(ret)
+        if adv_floor > 0:
+            ok &= adv[:, t] >= adv_floor
+        if ok.sum() < min_names:
+            t += horizon
+            continue
+        idx = np.where(ok)[0]
+        pct = pd.Series(sig[ok]).rank(pct=True).to_numpy()
+        w = np.zeros(C.shape[0])
+        if long_only:
+            if top_n > 0:
+                # 집중 동일가중 top-N: 적고 큰 비대칭 베팅(낮은 승률·높은 손익비).
+                sel = idx[np.argsort(-sig[ok])[:top_n]]
+                w[sel] = 1.0 / len(sel)
+            else:
+                lw = np.clip(pct - 0.5, 0, None)  # 북 전체 순위 틸트
+                w[idx] = lw / lw.sum() if lw.sum() > 0 else 0.0
+            bench = float(np.nanmean(ret[idx]))
+            gross = float(np.nansum(w * np.nan_to_num(ret))) - bench
+            short_gross = 0.0
+        else:
+            w[idx] = (pct - 0.5) / np.abs(pct - 0.5).sum()  # 달러중립, 총노출=1
+            gross = float(np.nansum(w * np.nan_to_num(ret)))
+            short_gross = float(np.abs(w[w < 0]).sum())  # 중립북이면 ~0.5
+        turnover = float(np.abs(w - prev_w).sum())
+        borrow = borrow_cost_annual * (horizon / 252.0) * short_gross
+        rows.append({"date": dates[t], "gross": gross, "turnover": turnover,
+                     "net": gross - turnover * cost_one_way - borrow})
+        prev_w = w
+        t += horizon
+
+    periods = pd.DataFrame(rows)
+    return periods, summarize_periods(periods, horizon)
+
+
+def staggered_tranche_backtest(
+    close: np.ndarray,
+    trade_value: np.ndarray,
+    signal: np.ndarray,
+    dates: list,
+    *,
+    horizon: int = 60,
+    step: int = 20,
+    top_n: int = 40,
+    adv_floor: float = 20000.0,
+    adv_window: int = 20,
+    start_index: int = 130,
+    min_names: int = 20,
+    cap_array: np.ndarray | None = None,
+    cap_rank: tuple[int, int] | None = None,
+    delisting_exit: bool = False,
+) -> tuple[pd.DataFrame, dict]:
+    """분할 진입 롱온리 초과수익 — ``horizon // step`` 개 트랜치를 겹쳐 보유.
+
+    ``step`` 일마다 새 트랜치를 top-N 으로 짜고, 지난 트랜치들(``t - k·step``)의 북을 함께
+    든다. 각 구간 수익은 트랜치별 북 평균 − 적격 유니버스 평균(벤치)의 평균이고, 회전율은
+    ``1/n_tranches`` 로 고정 보고한다(이 함수는 비용을 떼지 않는다 — ``net == gross``).
+
+    Args:
+        cap_array: ``code × date`` 시가총액 패널 또는 ``None``.
+        cap_rank: ``(lo, hi)`` 시총 순위 구간으로 유니버스 제한(``cap_array`` 와 함께).
+        delisting_exit: 보유 중 상장폐지된 종목의 손실을 반영할지.
+
+            기본 ``False`` 는 기존 동작이다: 폐지 후 가격이 NaN 이 되고 ``np.nanmean`` 이
+            그 종목을 **조용히 빼버린다** — 북과 벤치마크 양쪽을 낙관 쪽으로 왜곡한다.
+            ``True`` 면 마지막 관측 종가(정리매매 종료가)로 청산한 것으로 본다. 한국 시장은
+            폐지 전 정리매매(보통 7거래일)가 있어 임의 상수(-30% 등)보다 데이터에 충실하다.
+            다만 정리매매 자체를 못 판 경우는 반영되지 않으므로 이 역시 낙관 쪽 하한이다.
+
+    Returns:
+        ``(periods, summary)`` — periods 열은 ``date, gross, turnover, net, book, bench,
+        n_universe``. book/bench 를 함께 남기는 건 초과수익이 전략 개선인지 벤치 악화인지
+        가르기 위해서다(생존편향 같은 유니버스 변경에서 결론을 뒤집는다).
+    """
+    C = close
+    V = trade_value
+    sig_m = signal
+    nD = len(dates)
+    adv = _trailing_adv(V, nD, adv_window, C)
+    n_tranches = max(1, horizon // step)
+    capm = cap_array
+
+    # 폐지 청산가: 각 시점까지의 마지막 관측 종가(행 방향 forward-fill). 꺼져 있으면 안 만든다.
+    C_ff = pd.DataFrame(C).ffill(axis=1).to_numpy(float) if delisting_exit else None
+
+    # eligible/book 은 t 의 순수함수라 메모이즈해도 숫자가 안 바뀐다. 스태거링이 지난
+    # 리밸런스일을 다시 부르므로, 캐시가 없으면 같은 날 전유니버스 스캔이 트랜치 수만큼 반복된다.
+    _elig_cache: dict[int, np.ndarray] = {}
+    _book_cache: dict[int, np.ndarray | None] = {}
+
+    def eligible(t: int) -> np.ndarray:
+        cached = _elig_cache.get(t)
+        if cached is not None:
+            return cached
+        ok = np.isfinite(sig_m[:, t]) & (adv[:, t] >= adv_floor)
+        if capm is not None and cap_rank is not None:
+            liq = np.where(ok & np.isfinite(capm[:, t]))[0]
+            order = liq[np.argsort(-capm[liq, t])]  # 시총 내림차순
+            tier = order[cap_rank[0]:cap_rank[1]]
+            mask = np.zeros(C.shape[0], bool)
+            mask[tier] = True
+            ok = ok & mask
+        _elig_cache[t] = ok
+        return ok
+
+    def book(t: int) -> np.ndarray | None:
+        if t in _book_cache:
+            return _book_cache[t]
+        ok = eligible(t)
+        if ok.sum() < min_names:
+            _book_cache[t] = None
+            return None
+        idx = np.where(ok)[0]
+        out = idx[np.argsort(-sig_m[idx, t])[:top_n]]
+        _book_cache[t] = out
+        return out
+
+    rows: list[dict] = []
+    for t in range(start_index, nD - step - 1, step):
+        uni = np.where(eligible(t))[0]
+        if uni.size < min_names:
+            continue
+        ret = C[:, t + step] / C[:, t] - 1.0
+        if C_ff is not None:
+            # 진입 시점엔 가격이 있었는데 청산 시점에 없는 종목 = 보유 중 상장폐지.
+            gone = np.isfinite(C[:, t]) & ~np.isfinite(C[:, t + step])
+            ret[gone] = C_ff[gone, t + step] / C[gone, t] - 1.0
+        bench = float(np.nanmean(ret[uni]))
+        tranche_excess, tranche_book = [], []
+        for k in range(n_tranches):
+            b = book(t - k * step)
+            if b is not None:
+                book_ret = float(np.nanmean(ret[b]))
+                tranche_book.append(book_ret)
+                tranche_excess.append(book_ret - bench)
+        if tranche_excess:
+            rows.append({"date": dates[t], "gross": float(np.mean(tranche_excess)),
+                         "turnover": 1.0 / n_tranches, "net": float(np.mean(tranche_excess)),
+                         "book": float(np.mean(tranche_book)), "bench": bench,
+                         "n_universe": int(uni.size)})
+    periods = pd.DataFrame(rows)
+    return periods, summarize_periods(periods, step)
+
+
+def rank_ic(
+    close: np.ndarray,
+    trade_value: np.ndarray,
+    signal: np.ndarray,
+    dates: list,
+    *,
+    horizon: int = 40,
+    adv_floor: float = 5000.0,
+    adv_window: int = 20,
+    start_index: int = 130,
+    fresh_days: int = 0,
+    n_regimes: int = 4,
+    age: np.ndarray | None = None,
+) -> dict:
+    """신호 vs 선행수익의 일별 횡단면 순위 IC + Newey-West t + 국면별 분해.
+
+    적격 종목이 20개 미만인 날은 건너뛴다. HAC lag = ``horizon`` (겹치는 선행수익 보정).
+    ``dates`` 라벨의 앞 7자(``YYYY-MM``)가 국면 start/end 로 실린다.
+
+    Returns:
+        ``{"ic_mean", "ic_nw_t", "n_days", "frac_positive", "regimes"}``.
+    """
+    C = close
+    V = trade_value
+    yoy = signal
+    if age is None:
+        age = np.full_like(yoy, np.nan)
+    nD = len(dates)
+    adv = _trailing_adv(V, nD, adv_window, C)
+
+    ics: list[float] = []
+    ic_dates: list[str] = []
+    for t in range(start_index, nD - horizon - 1):
+        sig = yoy[:, t].copy()
+        if fresh_days > 0:
+            sig = np.where(age[:, t] <= fresh_days, sig, np.nan)
+        ok = np.isfinite(sig)
+        if adv_floor > 0:
+            ok &= adv[:, t] >= adv_floor
+        ret = C[:, t + 1 + horizon] / C[:, t + 1] - 1.0
+        ok &= np.isfinite(ret)
+        if ok.sum() < 20:
+            continue
+        a = pd.Series(sig[ok]).rank().to_numpy()
+        b = pd.Series(ret[ok]).rank().to_numpy()
+        if a.std() > 0 and b.std() > 0:
+            ics.append(float(np.corrcoef(a, b)[0, 1]))
+            ic_dates.append(dates[t])
+
+    ic = np.array(ics)
+    mean_ic, nw_t = newey_west_t(ic, horizon)
+    regimes: list[dict] = []
+    if len(ic) >= n_regimes:
+        b = len(ic) // n_regimes
+        for k in range(n_regimes):
+            s0 = k * b
+            s1 = (k + 1) * b if k < n_regimes - 1 else len(ic)
+            m, tt = newey_west_t(ic[s0:s1], horizon)
+            regimes.append({"start": ic_dates[s0][:7], "end": ic_dates[s1 - 1][:7],
+                            "ic_mean": m, "nw_t": tt})
+    return {
+        "ic_mean": mean_ic, "ic_nw_t": nw_t, "n_days": len(ic),
+        "frac_positive": float((ic > 0).mean()) if len(ic) else float("nan"),
+        "regimes": regimes,
+    }

krx_quant_core/backtest/fills.py

@@ -0,0 +1,62 @@
+"""지정가 체결 판정 — ``touch``(낙관) vs ``through``(보수) 두 가정.
+
+scalp-it 은 같은 판정을 두 곳에 들고 있다: 가상 포지션 회계
+(``realtime/risk_guard.py`` ``RiskGuard._advance``)와 dry-run 주문 실행기
+(``realtime/order_executor.py`` ``_is_buy_filled``·``_check_sell_fill``). 두 곳의 기준이
+갈리면 같은 틱열에서 회계와 실행기가 서로 다른 체결을 기록한다(2026-08-25 사고).
+그래서 판정식을 순수 함수 하나로 올린다.
+
+틱 체결가만 보고 내 지정가가 채워졌는지 추정한다 — 호가 큐 위치는 모른다:
+
+- **touch(낙관)**: 체결가가 내 지정가에 **닿기만** 하면 체결. 큐 맨 앞이라는 가정.
+  매수 ``trade <= limit``, 매도 ``trade >= limit``.
+- **through(보수, 기본)**: 체결가가 지정가를 **관통**해야 체결. 그 가격의 큐가 다
+  비워져야 내 주문까지 온다는 가정. 매수 ``trade < limit``, 매도 ``trade > limit``.
+  scalp-it 감사가 "through 를 실전 기대로" 요구해 기본값이다.
+
+부동소수 비교는 scalp-it 과 같은 ``1e-9`` 여유를 둔다(through 는 더 엄격한 쪽으로,
+touch 는 더 너그러운 쪽으로).
+
+원본과 한 가지 다르다: 알 수 없는 ``basis`` 문자열. 실행기는 조용히 through 로,
+회계는 조용히 touch 로 읽어 **서로 반대**였다. 여기서는 ``ValueError`` 를 낸다 — 두
+원본 모두 CLI 에서 ``choices=("through","touch")`` 로 막혀 있어 유효 입력에서는 동일하다.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+__all__ = ["EPS", "FILL_BASES", "FillBasis", "limit_buy_filled", "limit_sell_filled"]
+
+FillBasis = Literal["through", "touch"]
+FILL_BASES: tuple[str, ...] = ("through", "touch")
+
+#: scalp-it ``risk_guard._EPS`` / ``order_executor._EPS`` 와 같은 값.
+EPS = 1e-9
+
+
+def _check(basis: str) -> None:
+    if basis not in FILL_BASES:
+        raise ValueError(f"fill basis 는 {FILL_BASES} 중 하나여야 한다: {basis!r}")
+
+
+def limit_buy_filled(limit: float, trade_price: float, basis: FillBasis = "through") -> bool:
+    """매수 지정가 ``limit`` 이 체결가 ``trade_price`` 틱으로 채워졌다고 볼 수 있나.
+
+    through: ``trade_price < limit - EPS`` · touch: ``trade_price <= limit + EPS``.
+    """
+    _check(basis)
+    if basis == "through":
+        return trade_price < limit - EPS
+    return trade_price <= limit + EPS
+
+
+def limit_sell_filled(limit: float, trade_price: float, basis: FillBasis = "through") -> bool:
+    """매도 지정가 ``limit`` 이 채워졌다고 볼 수 있나 — 매수와 대칭(가격이 **위로** 가야 붙는다).
+
+    through: ``trade_price > limit + EPS`` · touch: ``trade_price >= limit - EPS``.
+    """
+    _check(basis)
+    if basis == "through":
+        return trade_price > limit + EPS
+    return trade_price >= limit - EPS

krx_quant_core/backtest/ledger.py

@@ -0,0 +1,262 @@
+"""트레이드 원장 — 체결 한 건(``Trade``), 비용 차감 순손익, 성과지표.
+
+``performance_metrics`` 는 daytrade-it ``application/handlers/backtest.py``
+``BacktestHandler._calculate_metrics`` 의 산식을 **그대로** 옮겼다. 반환형
+:class:`PerformanceMetrics` 의 필드·반올림 자릿수·``Decimal`` 타입도 daytrade 의
+``BacktestMetrics`` 와 같다 — 대시보드·MCP 도구가 그 모양을 이미 읽고 있어서, 산식을
+옮기면서 모양을 바꾸면 소비자 쪽 비교 테스트가 무의미해진다.
+
+그 산식의 관례(고치지 않고 보존한 것 — 바꾸면 기존 수치가 조용히 바뀐다):
+
+- 연환산 수익률은 **달력일** 기준 ``(end-start).days / 365.25`` 년.
+- Sharpe/Sortino 는 equity curve 의 일간 수익률로 ``mean·252 / (stdev·√252)``,
+  **무위험수익률 차감 없음**, 표본표준편차(``statistics.stdev``, ddof=1).
+- Sortino 의 하방편차는 음수 수익률들의 **표본표준편차**(0 기준 semideviation 이 아님).
+  음수 수익률이 2개 미만이면 전체 표준편차로 대체.
+- 손실 트레이드가 없으면 profit_factor 는 ``999`` 로 캡.
+- 최대낙폭은 equity curve 각 점의 ``drawdown``(양수 비율) 최대값이고, 금액은
+  ``max_dd × initial_capital`` (고점 자본이 아니라 초기자본 기준).
+- 무승부(pnl == 0) 는 승도 패도 아니지만 ``total_trades`` 와 승률 분모에는 들어간다.
+"""
+
+from __future__ import annotations
+
+import statistics
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from typing import Any, Literal
+
+__all__ = [
+    "PerformanceMetrics",
+    "Trade",
+    "TradeResult",
+    "apply_costs",
+    "performance_metrics",
+]
+
+Side = Literal["long", "short"]
+
+
+@dataclass(frozen=True)
+class Trade:
+    """체결된 트레이드 한 건. ``exit_ts``/``exit_price`` 가 None 이면 미청산.
+
+    ``side`` 는 포지션 방향(``"long"``·``"short"``)이다 — 주문 방향(BUY/SELL)이 아니다.
+    ``market`` 은 비용 함수가 KOSPI/KOSDAQ 세율을 고를 수 있게 실어 나른다.
+    """
+
+    code: str
+    side: Side
+    entry_ts: datetime
+    entry_price: float
+    exit_ts: datetime | None
+    exit_price: float | None
+    qty: float
+    market: str = "KOSPI"
+
+    @property
+    def closed(self) -> bool:
+        return self.exit_ts is not None and self.exit_price is not None
+
+    @property
+    def gross_pnl(self) -> float:
+        """비용 전 손익(원). 미청산이면 0."""
+        if not self.closed:
+            return 0.0
+        sign = 1.0 if self.side == "long" else -1.0
+        return (float(self.exit_price) - float(self.entry_price)) * float(self.qty) * sign
+
+    @property
+    def gross_return(self) -> float:
+        """비용 전 가격 수익률. 미청산이거나 진입가 0 이면 0."""
+        if not self.closed or not self.entry_price:
+            return 0.0
+        sign = 1.0 if self.side == "long" else -1.0
+        return (float(self.exit_price) - float(self.entry_price)) / float(self.entry_price) * sign
+
+
+@dataclass(frozen=True)
+class TradeResult:
+    """비용을 뗀 트레이드. ``pnl`` = ``gross_pnl - cost`` (원)."""
+
+    trade: Trade
+    gross_pnl: float
+    cost: float
+    pnl: float
+    pnl_pct: float
+
+    @property
+    def entry_ts(self) -> datetime:
+        return self.trade.entry_ts
+
+    @property
+    def exit_ts(self) -> datetime | None:
+        return self.trade.exit_ts
+
+
+def apply_costs(trades: Iterable[Trade], cost_fn: Callable[[Trade], float]) -> list[TradeResult]:
+    """트레이드마다 ``cost_fn(trade)`` (왕복 총비용, 원 — 수수료·세금·슬리피지)을 떼 순손익을 낸다.
+
+    비용 모델은 여기서 정하지 않는다(``krx_quant_core.costs`` 나 소비자 몫). 미청산
+    트레이드는 비용을 부르지 않고 손익 0 으로 둔다 — 아직 안 판 것에 매도세를 물리면
+    안 된다. ``pnl_pct`` 는 daytrade 관례대로 **비용 전** 가격 수익률이다.
+    """
+    out: list[TradeResult] = []
+    for t in trades:
+        if not t.closed:
+            out.append(TradeResult(t, 0.0, 0.0, 0.0, 0.0))
+            continue
+        gross = t.gross_pnl
+        cost = float(cost_fn(t))
+        out.append(TradeResult(t, gross, cost, gross - cost, t.gross_return))
+    return out
+
+
+@dataclass(frozen=True)
+class PerformanceMetrics:
+    """daytrade-it ``BacktestMetrics`` 와 같은 필드·타입."""
+
+    total_return: Decimal
+    total_return_pct: Decimal
+    annualized_return: Decimal
+    sharpe_ratio: Decimal
+    sortino_ratio: Decimal
+    max_drawdown: Decimal
+    max_drawdown_pct: Decimal
+    win_rate: Decimal
+    profit_factor: Decimal
+    total_trades: int
+    winning_trades: int
+    losing_trades: int
+    avg_win: Decimal
+    avg_loss: Decimal
+    avg_trade_duration_hours: Decimal
+    best_trade: Decimal
+    worst_trade: Decimal
+
+
+def _dec(x: Any) -> Decimal:
+    # daytrade 는 pnl 을 이미 Decimal(str(round(x, 2))) 로 들고 온다. float 가 들어와도
+    # str 경유로 바꿔 Decimal 합산을 유지한다 — float 합으로 바꾸면 반올림 경계가 흔들린다.
+    return x if isinstance(x, Decimal) else Decimal(str(x))
+
+
+def _ts(t: Any, which: str) -> datetime | None:
+    # core 는 entry_ts/exit_ts, daytrade BacktestTrade 는 entry_date/exit_date 다.
+    v = getattr(t, f"{which}_ts", None)
+    if v is None:
+        v = getattr(t, f"{which}_date", None)
+    return v
+
+
+def performance_metrics(
+    trades: Sequence[Any],
+    equity_curve: Sequence[Mapping[str, Any]],
+    initial_capital: Decimal | float,
+    *,
+    start_date: datetime,
+    end_date: datetime,
+) -> PerformanceMetrics:
+    """트레이드 목록·equity curve → 성과지표 (daytrade ``_calculate_metrics`` 와 수치 동일).
+
+    Args:
+        trades: ``pnl`` (순손익)과 ``entry_ts``/``exit_ts`` (또는 daytrade 의
+            ``entry_date``/``exit_date``) 속성을 가진 객체들. :class:`TradeResult` 가 맞다.
+            청산 시각이 None 인 트레이드는 집계에서 빠진다.
+        equity_curve: ``{"equity": float, "drawdown": float}`` 점들(시간순).
+        initial_capital: 초기자본.
+        start_date, end_date: 연환산 기간(달력일).
+    """
+    if not trades:
+        zero = Decimal("0")
+        return PerformanceMetrics(
+            total_return=zero, total_return_pct=zero, annualized_return=zero,
+            sharpe_ratio=zero, sortino_ratio=zero, max_drawdown=zero,
+            max_drawdown_pct=zero, win_rate=zero, profit_factor=zero,
+            total_trades=0, winning_trades=0, losing_trades=0,
+            avg_win=zero, avg_loss=zero, avg_trade_duration_hours=zero,
+            best_trade=zero, worst_trade=zero,
+        )
+    initial_capital = _dec(initial_capital)
+
+    closed = [t for t in trades if _ts(t, "exit") is not None]
+    pnl_of = {id(t): _dec(t.pnl) for t in closed}
+    winning = [t for t in closed if pnl_of[id(t)] > 0]
+    losing = [t for t in closed if pnl_of[id(t)] < 0]
+
+    total_pnl = sum(pnl_of[id(t)] for t in closed)
+    total_return_pct = total_pnl / initial_capital
+
+    days = (end_date - start_date).days
+    years = days / 365.25
+
+    if years > 0 and total_return_pct > -1:
+        annualized = (1 + float(total_return_pct)) ** (1 / years) - 1
+    else:
+        annualized = 0
+
+    win_rate = len(winning) / len(closed) if closed else 0
+
+    gross_profit = sum(pnl_of[id(t)] for t in winning)
+    gross_loss = abs(sum(pnl_of[id(t)] for t in losing))
+    profit_factor = gross_profit / gross_loss if gross_loss > 0 else Decimal("inf")
+
+    avg_win = gross_profit / len(winning) if winning else Decimal("0")
+    avg_loss = gross_loss / len(losing) if losing else Decimal("0")
+
+    max_dd = max(e["drawdown"] for e in equity_curve) if equity_curve else 0
+    max_dd_value = max_dd * float(initial_capital)
+
+    durations = []
+    for t in closed:
+        entry, exit_ = _ts(t, "entry"), _ts(t, "exit")
+        if entry and exit_:
+            durations.append((exit_ - entry).total_seconds() / 3600)
+    avg_duration = sum(durations) / len(durations) if durations else 0
+
+    pnls = [float(pnl_of[id(t)]) for t in closed]
+    best = max(pnls) if pnls else 0
+    worst = min(pnls) if pnls else 0
+
+    sharpe: float = 0
+    sortino: float = 0
+    if len(equity_curve) > 1:
+        daily_returns = []
+        for i in range(1, len(equity_curve)):
+            prev = equity_curve[i - 1]["equity"]
+            curr = equity_curve[i]["equity"]
+            if prev > 0:
+                daily_returns.append((curr - prev) / prev)
+        if daily_returns:
+            avg_return = statistics.mean(daily_returns)
+            std_return = statistics.stdev(daily_returns) if len(daily_returns) > 1 else 1
+            sharpe = (avg_return * 252) / (std_return * (252**0.5)) if std_return > 0 else 0
+            negative = [r for r in daily_returns if r < 0]
+            downside_std = statistics.stdev(negative) if len(negative) > 1 else std_return
+            sortino = (avg_return * 252) / (downside_std * (252**0.5)) if downside_std > 0 else 0
+
+    return PerformanceMetrics(
+        total_return=total_pnl,
+        total_return_pct=Decimal(str(round(float(total_return_pct), 4))),
+        annualized_return=Decimal(str(round(annualized, 4))),
+        sharpe_ratio=Decimal(str(round(sharpe, 2))),
+        sortino_ratio=Decimal(str(round(sortino, 2))),
+        max_drawdown=Decimal(str(round(max_dd_value, 2))),
+        max_drawdown_pct=Decimal(str(round(max_dd, 4))),
+        win_rate=Decimal(str(round(win_rate, 4))),
+        profit_factor=(
+            Decimal(str(round(float(profit_factor), 2)))
+            if profit_factor != Decimal("inf")
+            else Decimal("999")
+        ),
+        total_trades=len(closed),
+        winning_trades=len(winning),
+        losing_trades=len(losing),
+        avg_win=Decimal(str(round(float(avg_win), 2))),
+        avg_loss=Decimal(str(round(float(avg_loss), 2))),
+        avg_trade_duration_hours=Decimal(str(round(avg_duration, 1))),
+        best_trade=Decimal(str(round(best, 2))),
+        worst_trade=Decimal(str(round(worst, 2))),
+    )