Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(tools): separate northbound turnover after disclosure cutover

Haozhe Wu3ffcaccfe15e
diff --git a/agent/src/tools/northbound_tool.py b/agent/src/tools/northbound_tool.py
index 53503227c..c1fe8f5ee 100644
--- a/agent/src/tools/northbound_tool.py
+++ b/agent/src/tools/northbound_tool.py
@@ -208,9 +208,9 @@ class NorthboundFlowTool(BaseTool):
"whole mainland China A-share market: the aggregate net inflow from Hong "
"Kong, split into Shanghai-Connect (沪股通) and Shenzhen-Connect (深股通) "
"channels, as the latest realtime figure plus a recent daily history "
- "(units: 10k CNY from Eastmoney; the tushare fallback reports CNY "
- "million and documents the 2024-08-30 net-buy→turnover disclosure "
- "boundary in data.note). This is a market-level total, NOT per-stock flow (for a "
+ "(units: 10k CNY from Eastmoney; the tushare fallback reports pre-cutover "
+ "net buy and post-cutover turnover in CNY million, with turnover_* "
+ "fields and null net-flow fields after 2024-08-19). This is a market-level total, NOT per-stock flow (for a "
"given symbol's order-bucket inflow use get_fund_flow). Read-only; China "
"A-share market only. Example: get_northbound_flow(lookback_days=10)."
)
diff --git a/agent/src/tools/tushare_fallbacks.py b/agent/src/tools/tushare_fallbacks.py
index d9a13047b..100c465a1 100644
--- a/agent/src/tools/tushare_fallbacks.py
+++ b/agent/src/tools/tushare_fallbacks.py
@@ -178,17 +178,19 @@ def fetch_dragon_tiger(trade_date: str, code: str | None) -> dict[str, Any]:
return data
-#: HKEX stopped publishing northbound daily net buy on this date; tushare's
-#: ``hgt``/``sgt``/``north_money`` carry turnover from then on (issue #1481).
-_NORTHBOUND_SEMANTICS_BOUNDARY = "2024-08-30"
+#: Tushare's northbound fields changed to turnover at the 2024-08-19
+#: disclosure cutover (issue #1481). Keep the boundary explicit so a
+#: post-cutover turnover value cannot be returned under a net-flow key.
+_NORTHBOUND_SEMANTICS_BOUNDARY = "2024-08-19"
_NORTHBOUND_NOTE = (
"HKEX stopped publishing northbound daily net buy on "
f"{_NORTHBOUND_SEMANTICS_BOUNDARY}. From that date onward tushare's "
"hgt/sgt/north_money carry northbound TURNOVER (verified equal to the "
"HKEX official Stock Connect Daily Statistics Total Turnover to the "
- "cent); rows before the boundary are NET BUY. Both eras are in million "
- "CNY and are passed through unchanged."
+ "cent); rows before the boundary are NET BUY. Post-cutover rows are "
+ "returned under turnover_* fields and their net-flow fields are null. "
+ "Both eras are in million CNY."
)
@@ -197,7 +199,7 @@ def fetch_northbound_flow(*, lookback_days: int) -> dict[str, Any]:
Values are passed through in tushare's native unit (million CNY). The
legacy ×100 rescale to 10k CNY assumed every row was a net buy in
- million CNY, but the field semantics changed at the 2024-08-30 HKEX
+ million CNY, but the field semantics changed at the 2024-08-19 HKEX
disclosure reform: post-boundary rows are turnover (cross-verified
against HKEX official daily statistics, see issue #1481), so a single
constant factor cannot serve both eras. The envelope therefore keeps
@@ -207,14 +209,36 @@ def fetch_northbound_flow(*, lookback_days: int) -> dict[str, Any]:
rows = _records(_pro_api().moneyflow_hsgt(start_date=start_date, end_date=end_date))
history: list[dict[str, Any]] = []
for row in rows:
- history.append(
- {
- "trade_date": _dashed_date(row.get("trade_date")),
- "shanghai_connect": _to_float(row.get("hgt")),
- "shenzhen_connect": _to_float(row.get("sgt")),
- "total": _to_float(row.get("north_money")),
- }
- )
+ trade_date = _dashed_date(row.get("trade_date"))
+ if trade_date is None:
+ continue
+ shanghai = _to_float(row.get("hgt"))
+ shenzhen = _to_float(row.get("sgt"))
+ total = _to_float(row.get("north_money"))
+ if trade_date >= _NORTHBOUND_SEMANTICS_BOUNDARY:
+ history.append(
+ {
+ "trade_date": trade_date,
+ "shanghai_connect": None,
+ "shenzhen_connect": None,
+ "total": None,
+ "turnover_shanghai": shanghai,
+ "turnover_shenzhen": shenzhen,
+ "turnover_total": total,
+ }
+ )
+ else:
+ history.append(
+ {
+ "trade_date": trade_date,
+ "shanghai_connect": shanghai,
+ "shenzhen_connect": shenzhen,
+ "total": total,
+ "turnover_shanghai": None,
+ "turnover_shenzhen": None,
+ "turnover_total": None,
+ }
+ )
history.sort(key=lambda item: item.get("trade_date") or "")
history = history[-lookback_days:]
latest = history[-1] if history else {}
@@ -226,6 +250,9 @@ def fetch_northbound_flow(*, lookback_days: int) -> dict[str, Any]:
"shanghai_connect": latest.get("shanghai_connect"),
"shenzhen_connect": latest.get("shenzhen_connect"),
"total": latest.get("total"),
+ "turnover_shanghai": latest.get("turnover_shanghai"),
+ "turnover_shenzhen": latest.get("turnover_shenzhen"),
+ "turnover_total": latest.get("turnover_total"),
},
"history": history,
}
diff --git a/agent/tests/test_tushare_fallbacks.py b/agent/tests/test_tushare_fallbacks.py
index edeefcc5d..1f59e6c9d 100644
--- a/agent/tests/test_tushare_fallbacks.py
+++ b/agent/tests/test_tushare_fallbacks.py
@@ -74,13 +74,13 @@ def test_dragon_tiger_maps_top_list_and_top_inst() -> None:
def test_northbound_passes_through_million_yuan_with_semantics_note() -> None:
- """No ×100 rescale: post-2024-08-30 rows are turnover in million CNY
+ """No ×100 rescale: post-2024-08-19 rows are turnover in million CNY
(HKEX-verified, issue #1481); a constant factor cannot serve both eras,
so values pass through and the note documents the boundary."""
pro = SimpleNamespace(
moneyflow_hsgt=lambda **_: [
- {"trade_date": "20240102", "hgt": 12.0, "sgt": -2.0, "north_money": 10.0},
- {"trade_date": "20240103", "hgt": 3.5, "sgt": 1.0, "north_money": 4.5},
+ {"trade_date": "20240816", "hgt": -2568.22, "sgt": 100.0, "north_money": -2468.22},
+ {"trade_date": "20240819", "hgt": 46129.34, "sgt": 50000.0, "north_money": 96129.34},
]
)
with patch.object(tf, "_pro_api", return_value=pro), patch.object(
@@ -89,10 +89,16 @@ def test_northbound_passes_through_million_yuan_with_semantics_note() -> None:
data = tf.fetch_northbound_flow(lookback_days=2)
assert data["unit"] == "CNY million"
- assert data["history"][0]["shanghai_connect"] == 12.0
- assert data["history"][0]["total"] == 10.0
- assert data["realtime"]["total"] == 4.5
- assert "2024-08-30" in data["note"]
+ assert data["history"][0]["shanghai_connect"] == -2568.22
+ assert data["history"][0]["total"] == -2468.22
+ assert data["history"][0]["turnover_total"] is None
+ assert data["history"][1]["shanghai_connect"] is None
+ assert data["history"][1]["total"] is None
+ assert data["history"][1]["turnover_shanghai"] == 46129.34
+ assert data["history"][1]["turnover_total"] == 96129.34
+ assert data["realtime"]["total"] is None
+ assert data["realtime"]["turnover_total"] == 96129.34
+ assert "2024-08-19" in data["note"]
assert "turnover" in data["note"].lower()