Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(journal): pool PnL/drawdown/dividends per settlement currency

Jackzigend813dc6f0e86
diff --git a/agent/src/tools/trade_journal_tool.py b/agent/src/tools/trade_journal_tool.py
index cf89a029a..7fd1472bd 100644
--- a/agent/src/tools/trade_journal_tool.py
+++ b/agent/src/tools/trade_journal_tool.py
@@ -19,6 +19,7 @@ from typing import Any
import pandas as pd
+from backtest.engines._market_hooks import code_currency
from src.agent.tools import BaseTool
from src.tools.path_utils import safe_user_path
from src.tools.trade_journal_parsers import (
@@ -94,7 +95,10 @@ def pair_trades_fifo(
Returns:
List of dicts: symbol, buy_dt, sell_dt, qty, buy_price, sell_price,
- hold_days, pnl, pnl_pct. Unmatched positions are ignored.
+ hold_days, pnl, pnl_pct, side, currency. ``currency`` is the symbol's
+ settlement currency via :func:`backtest.engines._market_hooks.code_currency`,
+ so downstream sums never mix denominations (#1808). Unmatched
+ positions are ignored.
"""
longs: dict[str, deque] = defaultdict(deque)
shorts: dict[str, deque] = defaultdict(deque)
@@ -152,6 +156,7 @@ def pair_trades_fifo(
"pnl": round(pnl, 2),
"pnl_pct": round(pnl_pct, 4),
"side": "short",
+ "currency": code_currency(row.symbol),
})
lot["fee"] -= entry_fee
lot["qty"] -= consumed
@@ -203,6 +208,7 @@ def pair_trades_fifo(
"pnl": round(pnl, 2),
"pnl_pct": round(pnl_pct, 4),
"side": "long",
+ "currency": code_currency(row.symbol),
})
lot["fee"] -= buy_fee
lot["qty"] -= consumed
@@ -231,12 +237,24 @@ def _compute_profile(df: pd.DataFrame) -> dict[str, Any]:
dividend cash rows; those are summed into ``total_dividends`` and
``total_pnl`` but never counted as trades.
+ Money is never summed across currencies (#1808). With a single
+ settlement currency, ``total_pnl`` / ``max_drawdown`` / ``total_dividends``
+ stay plain floats and the profile is byte-for-byte the legacy shape. When
+ round-trips span more than one currency they become per-currency dicts
+ (e.g. ``{"USD": 100.0, "HKD": 1000.0}``) plus a ``currency_warning`` —
+ the same no-FX-conversion convention the shadow backtest reports
+ (#997/#1310). Ratio metrics (win_rate, profit_loss_ratio) stay
+ dimensionless on the full sample. Dividend rows settle in their symbol's
+ currency, so they join that currency's pool even when the market has no
+ round-trip here — the cash is real and dropping it would understate the
+ pool.
+
Returns:
Dict with avg_holding_days, trade_frequency_per_week, win_rate,
profit_loss_ratio, total_pnl, total_dividends,
dividend_rows_missing_cash, max_drawdown,
top_symbols, market_distribution, hourly_distribution,
- roundtrips_sample.
+ roundtrips_sample, and currency_warning when mixed.
"""
if df.empty:
return {"error": "empty trade journal"}
@@ -245,8 +263,19 @@ def _compute_profile(df: pd.DataFrame) -> dict[str, Any]:
rts_df = pd.DataFrame(rts)
trades_df = df[df["side"].isin(("buy", "sell"))]
- dividend_amounts = df.loc[df["side"] == "dividend", "amount"]
+ # Per-currency dividend split: a dividend settles in its symbol's
+ # currency, so it joins that currency's pool even when the market has no
+ # round-trip in this journal — the cash is real, dropping it would be a
+ # silent omission (#1808).
+ div_rows = df[df["side"] == "dividend"]
+ dividend_amounts = div_rows["amount"]
total_dividends = round(float(dividend_amounts.sum()), 2)
+ dividends_by_currency: dict[str, float] = {}
+ for symbol, amount in div_rows.groupby("symbol")["amount"].sum().items():
+ cur = code_currency(symbol)
+ dividends_by_currency[cur] = (
+ dividends_by_currency.get(cur, 0.0) + float(amount)
+ )
# A dividend row that parsed with no cash is almost never a real zero
# payout — it means the export named its cash column something the parser
# did not recognise, and the payout would otherwise be booked as 0 with
@@ -259,6 +288,12 @@ def _compute_profile(df: pd.DataFrame) -> dict[str, Any]:
span_days = max(1, (df["datetime"].max() - df["datetime"].min()).days)
freq_per_week = round(total_trades / span_days * 7, 2)
+ currencies = sorted(
+ {rt.get("currency") or "UNKNOWN" for rt in rts}
+ | set(dividends_by_currency)
+ )
+ mixed = len(currencies) > 1
+
if not rts_df.empty:
wins = rts_df[rts_df["pnl"] > 0]
losses = rts_df[rts_df["pnl"] < 0]
@@ -267,12 +302,31 @@ def _compute_profile(df: pd.DataFrame) -> dict[str, Any]:
win_rate = round(len(wins) / len(rts_df), 4)
pnl_ratio = round(_safe_div(avg_win, abs(avg_loss)), 2) if avg_loss else float("inf") if avg_win else 0.0
avg_hold = round(rts_df["hold_days"].mean(), 2)
- total_pnl = round(rts_df["pnl"].sum() + total_dividends, 2)
- # Cumulative PnL → max drawdown
- cum = rts_df.sort_values("sell_dt")["pnl"].cumsum()
- running_max = cum.cummax()
- drawdown = (cum - running_max).min()
- max_drawdown = round(float(drawdown), 2) if pd.notna(drawdown) else 0.0
+ if mixed:
+ # Per-currency pools, dividends included where their market
+ # traded; no FX translation (shadow-backtest convention #997/#1310).
+ total_pnl = {
+ cur: round(float(
+ rts_df.loc[rts_df["currency"] == cur, "pnl"].sum()
+ + dividends_by_currency.get(cur, 0.0)
+ ), 2)
+ for cur in currencies
+ }
+ max_drawdown = {}
+ for cur in currencies:
+ pool = rts_df[rts_df["currency"] == cur].sort_values("sell_dt")
+ pnl = pool["pnl"].cumsum()
+ drawdown = (pnl - pnl.cummax()).min()
+ max_drawdown[cur] = (
+ round(float(drawdown), 2) if pd.notna(drawdown) else 0.0
+ )
+ else:
+ total_pnl = round(float(rts_df["pnl"].sum()) + total_dividends, 2)
+ # Cumulative PnL → max drawdown
+ cum = rts_df.sort_values("sell_dt")["pnl"].cumsum()
+ running_max = cum.cummax()
+ drawdown = (cum - running_max).min()
+ max_drawdown = round(float(drawdown), 2) if pd.notna(drawdown) else 0.0
else:
win_rate = pnl_ratio = avg_hold = max_drawdown = 0.0
total_pnl = total_dividends
@@ -314,6 +368,17 @@ def _compute_profile(df: pd.DataFrame) -> dict[str, Any]:
"market_distribution": market_dist,
"hourly_distribution": hourly_dist,
"roundtrips_sample": roundtrips_sample,
+ **({
+ "currencies": currencies,
+ "total_dividends_by_currency": {
+ cur: round(dividends_by_currency.get(cur, 0.0), 2)
+ for cur in currencies
+ },
+ "currency_warning": (
+ "Round-trips span multiple settlement currencies; totals are "
+ "reported per currency with no FX conversion."
+ ),
+ } if mixed else {}),
}
diff --git a/agent/tests/test_trade_journal_currency_pools.py b/agent/tests/test_trade_journal_currency_pools.py
new file mode 100644
index 000000000..ed4f24914
--- /dev/null
+++ b/agent/tests/test_trade_journal_currency_pools.py
@@ -0,0 +1,142 @@
+"""Per-currency profile totals for mixed-currency journals (#1808).
+
+``_compute_profile`` used to sum the round-trip ``pnl`` column directly, so a
+Futu 综合账户 journal with both HK and US legs added HKD and USD as one
+number. Round-trips now carry their settlement currency
+(:func:`backtest.engines._market_hooks.code_currency`), and money totals are
+pooled per currency with no FX conversion — the convention the shadow
+backtest already reports (#997/#1310). Single-currency journals keep the
+legacy flat-float shape.
+"""
+
+from __future__ import annotations
+
+from src.tools.trade_journal_parsers import TradeRecord, records_to_dataframe
+from src.tools.trade_journal_tool import _compute_profile, pair_trades_fifo
+
+
+def _rec(
+ dt: str, symbol: str, side: str, qty: float, price: float, fee: float = 0.0
+) -> TradeRecord:
+ return TradeRecord(
+ datetime=dt,
+ symbol=symbol,
+ name="",
+ side=side,
+ quantity=qty,
+ price=price,
+ amount=qty * price,
+ fee=fee,
+ market="other",
+ )
+
+
+def _df(records: list[TradeRecord]):
+ return records_to_dataframe(records)
+
+
+def test_roundtrips_carry_settlement_currency() -> None:
+ df = _df([
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ ])
+ rts = pair_trades_fifo(df)
+ assert rts[0]["currency"] == "HKD"
+
+
+def test_mixed_currency_journal_pools_pnl_per_currency() -> None:
+ """The #1808 repro: HKD and USD must never be one headline number."""
+ df = _df([
+ # HK leg: 1000 HKD win
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ # US legs: +200 win then -300 loss → USD pool drawdown -300
+ _rec("2026-01-03 09:30:00", "AAPL", "buy", 100, 150.0),
+ _rec("2026-01-06 09:30:00", "AAPL", "sell", 100, 152.0),
+ _rec("2026-01-03 09:30:00", "MSFT", "buy", 100, 100.0),
+ _rec("2026-01-09 09:30:00", "MSFT", "sell", 100, 97.0),
+ ])
+ profile = _compute_profile(df)
+
+ assert profile["total_pnl"] == {"HKD": 1000.0, "USD": -100.0}
+ assert profile["max_drawdown"] == {"HKD": 0.0, "USD": -300.0}
+ # Ratio metrics stay dimensionless on the full sample.
+ assert profile["total_roundtrips"] == 3
+ assert profile["win_rate"] == round(2 / 3, 4)
+ assert profile["currencies"] == ["HKD", "USD"]
+ assert "no FX conversion" in profile["currency_warning"]
+ assert profile["total_dividends_by_currency"] == {"HKD": 0.0, "USD": 0.0}
+
+
+def test_single_currency_journal_keeps_legacy_shape() -> None:
+ """One currency → plain floats, no split keys: zero behavior change."""
+ df = _df([
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ ])
+ profile = _compute_profile(df)
+ assert profile["total_pnl"] == 1000.0
+ assert profile["max_drawdown"] == 0.0
+ assert isinstance(profile["total_pnl"], float)
+ assert "currencies" not in profile
+ assert "currency_warning" not in profile
+
+
+def test_dividends_join_their_own_currency_pool() -> None:
+ df = _df([
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ _rec("2026-01-06 09:30:00", "AAPL", "buy", 100, 150.0),
+ _rec("2026-01-09 09:30:00", "AAPL", "sell", 100, 151.0),
+ # HKD dividend joins the HKD pool, not a blended sum.
+ _div("2026-01-07 09:30:00", "0700.HK", 50.0),
+ ])
+ profile = _compute_profile(df)
+ assert profile["total_pnl"] == {"HKD": 1050.0, "USD": 100.0}
+ assert profile["total_dividends"] == 50.0
+ assert profile["total_dividends_by_currency"] == {"HKD": 50.0, "USD": 0.0}
+
+
+def _div(dt: str, symbol: str, amount: float) -> TradeRecord:
+ return TradeRecord(
+ datetime=dt,
+ symbol=symbol,
+ name="",
+ side="dividend",
+ quantity=0.0,
+ price=0.0,
+ amount=amount,
+ fee=0.0,
+ market="other",
+ )
+
+
+def test_foreign_dividend_flips_profile_to_its_currency_pool() -> None:
+ """A dividend in a currency with no round-trip still joins its own pool.
+
+ The cash is real — pooling it with HKD round-trips (the legacy sum) would
+ add USD to HKD, the exact bug #1808 describes. So it both flips the
+ profile to the split shape and lands in its own pool.
+ """
+ df = _df([
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ _div("2026-01-07 09:30:00", "AAPL", 25.0),
+ ])
+ profile = _compute_profile(df)
+ assert profile["total_pnl"] == {"HKD": 1000.0, "USD": 25.0}
+ assert profile["total_dividends"] == 25.0
+ assert profile["total_dividends_by_currency"] == {"HKD": 0.0, "USD": 25.0}
+
+
+def test_unmatched_positions_do_not_break_currency_pooling() -> None:
+ """An open USD position alongside closed HKD legs stays single-pool."""
+ df = _df([
+ _rec("2026-01-02 09:30:00", "0700.HK", "buy", 100, 300.0),
+ _rec("2026-01-05 09:30:00", "0700.HK", "sell", 100, 310.0),
+ # Never sold → no round-trip, must not flip the profile to mixed.
+ _rec("2026-01-06 09:30:00", "AAPL", "buy", 10, 150.0),
+ ])
+ profile = _compute_profile(df)
+ assert profile["total_pnl"] == 1000.0
+ assert "currency_warning" not in profile