stock-analysis-plugin 0.2.11 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/README.md +231 -381
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +131 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +630 -0
  7. package/mcp_host/__init__.py +1 -0
  8. package/mcp_host/__main__.py +3 -0
  9. package/mcp_host/server.py +222 -0
  10. package/package.json +7 -1
  11. package/pi/index.ts +52 -2906
  12. package/scripts/cli-json.mjs +23 -0
  13. package/scripts/exec-process.mjs +89 -0
  14. package/scripts/setup-python.mjs +37 -4
  15. package/scripts/tool-calls.mjs +489 -0
  16. package/skills/event-driven/SKILL.md +2 -2
  17. package/skills/growth-quality/SKILL.md +1 -1
  18. package/skills/stock-analysis/SKILL.md +8 -6
  19. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  20. package/tools/_cache.py +13 -0
  21. package/tools/_subproc.py +46 -0
  22. package/tools/alert_rules.py +2 -2
  23. package/tools/backtest.py +3 -3
  24. package/tools/capabilities.py +32 -9
  25. package/tools/cli_budgets.json +2 -0
  26. package/tools/diagnostics.py +3 -4
  27. package/tools/gather.py +2 -6
  28. package/tools/import_parser.py +3 -4
  29. package/tools/lixinger.py +119 -27
  30. package/tools/market_regime.py +5 -2
  31. package/tools/market_review.py +5 -6
  32. package/tools/name_resolver.py +66 -7
  33. package/tools/report_renderer.py +3 -3
  34. package/tools/requirements.txt +5 -4
  35. package/tools/risk_screening.py +3 -2
  36. package/tools/screener.py +6 -4
  37. package/tools/search_intel.py +79 -10
  38. package/tools/sec_edgar.py +266 -0
  39. package/tools/sec_holders.py +6 -0
  40. package/tools/signal_tracker.py +5 -5
  41. package/tools/stateless_analysis.py +115 -0
  42. package/tools/stock_data.py +455 -201
  43. package/tools/tiaa_disclosures.py +4 -0
  44. package/tools/tool_schemas.json +2704 -0
  45. package/tools/trading_calendar.py +65 -30
  46. package/tools/value_data.py +366 -134
  47. package/tools/watchlist.py +43 -5
@@ -6,7 +6,7 @@ import json
6
6
  import os
7
7
  import re
8
8
  import sys
9
- from datetime import date, timedelta
9
+ from datetime import date, datetime, timedelta
10
10
  from html import unescape
11
11
  from io import StringIO
12
12
  from pathlib import Path
@@ -18,8 +18,11 @@ import pandas as pd
18
18
 
19
19
  sys.path.insert(0, str(Path(__file__).resolve().parent))
20
20
  from _cache import DAY, cached
21
- from _subproc import scrub_secrets, socket_timeout, utf8_stdio
22
- from stock_data import _A_INDEX_RE, _cn_code, _yf_hk_symbol, detect_market, normalize_stock_code
21
+ from _subproc import error_message, scrub_secrets, socket_timeout, utf8_stdio
22
+ from stock_data import _A_INDEX_RE, _cn_code, _cn_now, _yf_hk_symbol, detect_market, normalize_stock_code
23
+ from trading_calendar import _MARKET_TZ, market_now
24
+
25
+ YF_MARKETS = ("US", "JP", "KR", "TW")
23
26
 
24
27
 
25
28
  def records(frame):
@@ -51,6 +54,24 @@ def capture(result, key, fetch):
51
54
  result.setdefault("warnings", []).append(f"{key}: unavailable ({type(exc).__name__})")
52
55
 
53
56
 
57
+ def yf_symbol(symbol):
58
+ market = detect_market(symbol)
59
+ if market == "HK":
60
+ return _yf_hk_symbol(symbol)
61
+ if market not in YF_MARKETS or symbol.startswith("^"):
62
+ raise ValueError("a listed stock symbol is required")
63
+ if market == "US" and not re.fullmatch(r"[A-Za-z][A-Za-z0-9.-]{0,14}", symbol):
64
+ raise ValueError("a listed stock symbol is required (HK codes need .HK)") # "" / "00700" fall back to US
65
+ return symbol.upper().replace(".", "-") if market == "US" else symbol.upper()
66
+
67
+
68
+ def market_date(value, market):
69
+ parsed = pd.to_datetime(value, errors="coerce")
70
+ if pd.notna(parsed) and parsed.tzinfo is not None:
71
+ parsed = parsed.tz_convert(_MARKET_TZ["CN" if market == "A" else market])
72
+ return parsed.date().isoformat() if pd.notna(parsed) else None
73
+
74
+
54
75
  def stock_identity(symbol):
55
76
  market = detect_market(symbol)
56
77
  if _A_INDEX_RE.fullmatch(symbol):
@@ -81,42 +102,91 @@ def valuation_summary(history, field):
81
102
  }
82
103
 
83
104
 
105
+ def as_of(events, day):
106
+ """Latest event filed on or before day (events sorted by filed)."""
107
+ found = None
108
+ for event in events:
109
+ if event["filed"] > day:
110
+ break
111
+ found = event
112
+ return found
113
+
114
+
115
+ def us_valuation_history(args):
116
+ import sec_edgar
117
+ import yfinance as yf
118
+
119
+ symbol = yf_symbol(args.symbol)
120
+ facts = sec_edgar.valuation_facts(symbol)
121
+ ticker = yf.Ticker(symbol)
122
+ start = (market_now("US").date() - pd.DateOffset(years=args.years)).date()
123
+ # Close is split-adjusted to today's share basis; scale filed share counts by splits after their as-of date.
124
+ closes = ticker.history(start=start.isoformat(), auto_adjust=False)["Close"].dropna()
125
+ if closes.empty:
126
+ raise ValueError("US price history unavailable")
127
+ closes = closes.resample("W-FRI").last().dropna() # weekly samples keep 10-year output bounded
128
+ splits = {market_date(stamp, "US"): float(ratio) for stamp, ratio in ticker.splits.items() if ratio > 0}
129
+ events = {key: sorted(facts[key], key=lambda e: e["filed"]) for key in ("ttm_net_income", "equity", "shares")}
130
+ history = []
131
+ for stamp, close in closes.items():
132
+ day = market_date(stamp, "US")
133
+ shares, income, equity = (as_of(events[key], day) for key in ("shares", "ttm_net_income", "equity"))
134
+ if not shares:
135
+ continue
136
+ factor = float(np.prod([ratio for split_day, ratio in splits.items() if split_day > shares["end"]]))
137
+ cap = float(close) * shares["val"] * factor
138
+ history.append(
139
+ {
140
+ "date": day,
141
+ "pe_ttm": round(cap / income["val"], 4) if income and income["val"] else None,
142
+ "pb": round(cap / equity["val"], 4) if equity and equity["val"] else None,
143
+ }
144
+ )
145
+ if not history:
146
+ raise ValueError("no US valuation history available")
147
+ return {
148
+ "symbol": args.symbol,
149
+ "market": "US",
150
+ "source": "sec_companyfacts+yfinance",
151
+ "requested_years": args.years,
152
+ "sampling": "weekly",
153
+ "share_basis": facts["share_basis"],
154
+ "history": history,
155
+ "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
156
+ "warnings": [
157
+ "Derived: market cap = weekly close x latest SEC-filed share count; PE uses TTM NetIncomeLoss attributable to parent, "
158
+ "PB uses StockholdersEquity, each effective from its filing date. "
159
+ "Multi-class issuers sum all classes at one class price."
160
+ ],
161
+ }
162
+
163
+
84
164
  def valuation_history(args):
85
165
  import akshare as ak
86
166
 
87
- market, symbol = stock_identity(args.symbol)
88
167
  if not 1 <= args.years <= 10:
89
- raise ValueError("valuation history requires an A/HK symbol and years in 1..10")
168
+ raise ValueError("years must be in 1..10")
169
+ if detect_market(args.symbol) == "US":
170
+ return us_valuation_history(args)
171
+ market, symbol = stock_identity(args.symbol)
90
172
  warning = None
91
- if market == "HK":
92
- if os.environ.get("LIXINGER_TOKEN"):
93
- try:
94
- from lixinger import hk_data
95
-
96
- rows = hk_data(args.symbol, "fundamental", ["pe_ttm", "pb"])
97
- cutoff = (date.today() - pd.DateOffset(years=args.years)).date().isoformat()
98
- history = sorted(
99
- [
100
- {"date": iso(r.get("date")), "pe_ttm": number(r.get("pe_ttm")), "pb": number(r.get("pb"))}
101
- for r in rows
102
- if iso(r.get("date")) and iso(r.get("date")) >= cutoff
103
- ],
104
- key=lambda r: r["date"],
105
- )
106
- if not history or not all(any(r[field] is not None for r in history) for field in ("pe_ttm", "pb")):
107
- raise ValueError("Lixinger HK valuation history incomplete")
108
- return {
109
- "symbol": args.symbol,
110
- "market": market,
111
- "source": "lixinger",
112
- "requested_years": args.years,
113
- "history": history,
114
- "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
115
- }
116
- except Exception:
117
- warning = "Lixinger HK unavailable; Baidu history retained without mixing sources"
118
- else:
119
- warning = "LIXINGER_TOKEN not configured; HK history limited to available Baidu data"
173
+ if os.environ.get("LIXINGER_TOKEN"):
174
+ try:
175
+ import lixinger
176
+
177
+ history = lixinger.valuation_history("cn" if market == "A" else "hk", symbol, args.years)
178
+ return {
179
+ "symbol": args.symbol,
180
+ "market": market,
181
+ "source": "lixinger",
182
+ "requested_years": args.years,
183
+ "history": history,
184
+ "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
185
+ }
186
+ except Exception as e:
187
+ warning = f"Lixinger {market} unavailable: {error_message(e)}; Baidu history used without mixing sources"
188
+ elif market == "HK":
189
+ warning = "LIXINGER_TOKEN not configured; HK history limited to available Baidu data"
120
190
  fetch = ak.stock_zh_valuation_baidu if market == "A" else ak.stock_hk_valuation_baidu
121
191
  period = "近一年" if args.years == 1 else "近三年" if args.years <= 3 else "近五年" if args.years <= 5 else "近十年"
122
192
  if market == "HK" and args.years > 3:
@@ -133,7 +203,7 @@ def valuation_history(args):
133
203
  ),
134
204
  )
135
205
  merged = {}
136
- cutoff = (date.today() - timedelta(days=365.25 * args.years)).isoformat()
206
+ cutoff = (_cn_now().date() - timedelta(days=365.25 * args.years)).isoformat()
137
207
  for field in ("pe_ttm", "pb"):
138
208
  for row in series.get(field, []):
139
209
  stamp = iso(row.get("date"))
@@ -160,28 +230,22 @@ INDEX_NAMES = {
160
230
  }
161
231
 
162
232
 
233
+ def _csi_hist(ak):
234
+ # akshare 1.20.44 renamed it; py3.10 stays below 1.20.40 with the old name.
235
+ return getattr(ak, "index_hist_csindex", None) or ak.stock_zh_index_hist_csindex
236
+
237
+
163
238
  def lixinger_index_history(code, start, end):
164
- import requests
239
+ import lixinger
165
240
 
166
241
  def fetch():
167
- response = requests.post(
168
- "https://open.lixinger.com/api/cn/index/fundamental",
169
- json={
170
- "token": os.environ["LIXINGER_TOKEN"],
171
- "stockCodes": [code],
172
- "startDate": start,
173
- "endDate": end,
174
- "metricsList": ["pe_ttm.mcw", "pb.mcw"],
175
- },
176
- timeout=20,
242
+ data = lixinger.post(
243
+ "cn/index/fundamental",
244
+ {"stockCodes": [code], "startDate": start, "endDate": end, "metricsList": ["pe_ttm.mcw", "pb.mcw"]},
177
245
  )
178
- response.raise_for_status()
179
- payload = response.json()
180
- if payload.get("code") != 1:
181
- raise ValueError("Lixinger index data unavailable; check token permissions")
182
246
  rows = [
183
247
  {"date": iso(r.get("date")), "pe_ttm": number(r.get("pe_ttm.mcw")), "pb": number(r.get("pb.mcw"))}
184
- for r in payload.get("data", [])
248
+ for r in data
185
249
  if r.get("stockCode") == code
186
250
  ]
187
251
  if not rows or not any(r["date"] and (r["pe_ttm"] is not None or r["pb"] is not None) for r in rows):
@@ -201,7 +265,7 @@ def index_valuation(args):
201
265
  raise ValueError("years must be in 1..10")
202
266
  result = {"symbol": code, "name": name, "source": "legulegu", "requested_years": args.years}
203
267
  merged = {}
204
- cutoff = (pd.Timestamp(date.today()) - pd.DateOffset(years=args.years)).date().isoformat()
268
+ cutoff = (pd.Timestamp(_cn_now().date()) - pd.DateOffset(years=args.years)).date().isoformat()
205
269
  for field, fn, column in [("pe_ttm", ak.stock_index_pe_lg, "滚动市盈率"), ("pb", ak.stock_index_pb_lg, "市净率")]:
206
270
  section = {}
207
271
  capture(
@@ -211,7 +275,7 @@ def index_valuation(args):
211
275
  )
212
276
  for row in section.get("rows", []):
213
277
  stamp = iso(row.get("日期"))
214
- if stamp and cutoff <= stamp <= date.today().isoformat():
278
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat():
215
279
  merged.setdefault(stamp, {"date": stamp})[field] = number(row.get(column))
216
280
  result.setdefault("warnings", []).extend(section.get("warnings", []))
217
281
  if not any(number(r.get("pe_ttm")) is not None for r in merged.values()) and re.fullmatch(
@@ -223,24 +287,27 @@ def index_valuation(args):
223
287
  "history",
224
288
  lambda: dataset(
225
289
  f"csi-history:{code}:{args.years}",
226
- lambda: ak.stock_zh_index_hist_csindex(
227
- symbol=code, start_date=cutoff.replace("-", ""), end_date=date.today().strftime("%Y%m%d")
290
+ lambda: _csi_hist(ak)(
291
+ symbol=code, start_date=cutoff.replace("-", ""), end_date=_cn_now().date().strftime("%Y%m%d")
228
292
  ),
229
293
  ),
230
294
  )
231
295
  for row in section.get("history", []):
232
296
  stamp = iso(row.get("日期"))
233
297
  pe = number(row.get("滚动市盈率"))
234
- if stamp and cutoff <= stamp <= date.today().isoformat() and pe is not None:
298
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat() and pe is not None:
235
299
  merged.setdefault(stamp, {"date": stamp})["pe_ttm"] = pe
236
300
  capture(
237
301
  section,
238
302
  "recent",
239
- lambda: dataset(f"csi-valuation:{code}", lambda: ak.stock_zh_index_value_csindex(symbol=code)),
303
+ lambda: dataset(
304
+ f"csi-valuation:{code}",
305
+ lambda: (getattr(ak, "index_value_csindex", None) or ak.stock_zh_index_value_csindex)(symbol=code),
306
+ ),
240
307
  )
241
308
  for row in section.get("recent", []):
242
309
  stamp = iso(row.get("日期"))
243
- if stamp and cutoff <= stamp <= date.today().isoformat():
310
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat():
244
311
  merged.setdefault(stamp, {"date": stamp}).update(
245
312
  pe=number(row.get("市盈率1")), dividend_yield=number(row.get("股息率1"))
246
313
  )
@@ -258,9 +325,9 @@ def index_valuation(args):
258
325
  missing = [field for field in ("pe_ttm", "pb") if field not in result["metric_sources"]]
259
326
  if missing and os.environ.get("LIXINGER_TOKEN") and re.fullmatch(r"\d{6}|H\d{5}", code, re.I):
260
327
  section = {}
261
- capture(section, "rows", lambda: lixinger_index_history(code, cutoff, date.today().isoformat()))
328
+ capture(section, "rows", lambda: lixinger_index_history(code, cutoff, _cn_now().date().isoformat()))
262
329
  for row in section.get("rows", []):
263
- if row["date"] and cutoff <= row["date"] <= date.today().isoformat():
330
+ if row["date"] and cutoff <= row["date"] <= _cn_now().date().isoformat():
264
331
  for field in missing:
265
332
  if row[field] is not None:
266
333
  merged.setdefault(row["date"], {"date": row["date"]})[field] = row[field]
@@ -334,32 +401,38 @@ def earnings_calendar(args):
334
401
  suffix = {"03-31": "一季", "06-30": "半年报", "09-30": "三季", "12-31": "年报"}
335
402
  if not 1 <= args.top <= 500 or (args.report_date and not stamp):
336
403
  raise ValueError("report_date must be a valid date and top must be in 1..500")
337
- if args.symbol and detect_market(args.symbol) == "HK":
404
+ market = detect_market(args.symbol) if args.symbol else "A"
405
+ if market in ("KR", "TW"):
406
+ raise ValueError("earnings calendar covers A/HK/US/JP only")
407
+ if market in ("HK", "US", "JP"):
338
408
  import yfinance as yf
339
409
 
340
- _, hk_code = stock_identity(args.symbol)
341
- sections = {}
342
- for board in ("main", "gem"):
343
- capture(sections, board, lambda board=board: hk_board_meetings(board))
344
- events = [
345
- r
346
- for board in ("main", "gem")
347
- for r in sections.get(board, [])
348
- if r["symbol"] == hk_code + ".HK"
349
- and r["scheduled_date"] >= date.today().isoformat()
350
- and (not stamp or r["report_date"] == stamp)
351
- ]
352
- events = list({(r["scheduled_date"], r["purpose"], r["report_date"]): r for r in events}.values())
353
- events.sort(key=lambda r: r["scheduled_date"])
410
+ code = yf_symbol(args.symbol)
411
+ today = market_now(market).date().isoformat()
412
+ sections, events = {}, []
413
+ if market == "HK":
414
+ hk_code = stock_identity(args.symbol)[1]
415
+ for board in ("main", "gem"):
416
+ capture(sections, board, lambda board=board: hk_board_meetings(board))
417
+ events = [
418
+ r
419
+ for board in ("main", "gem")
420
+ for r in sections.get(board, [])
421
+ if r["symbol"] == hk_code + ".HK"
422
+ and r["scheduled_date"] >= today
423
+ and (not stamp or r["report_date"] == stamp)
424
+ ]
425
+ events = list({(r["scheduled_date"], r["purpose"], r["report_date"]): r for r in events}.values())
426
+ events.sort(key=lambda r: r["scheduled_date"])
354
427
 
355
428
  def fetch():
356
- frame = yf.Ticker(_yf_hk_symbol(args.symbol)).get_earnings_dates(limit=12)
429
+ frame = yf.Ticker(code).get_earnings_dates(limit=12)
357
430
  if frame is None:
358
- raise ValueError("HK earnings schedule unavailable")
359
- return sorted({iso(d) for d in frame.index if iso(d)})
431
+ raise ValueError(f"{market} earnings schedule unavailable")
432
+ return sorted({market_date(d, market) for d in frame.index if market_date(d, market)})
360
433
 
361
434
  if not events:
362
- capture(sections, "dates", lambda: cached(f"hk-earnings-schedule:{_yf_hk_symbol(args.symbol)}", DAY, fetch))
435
+ capture(sections, "dates", lambda: cached(f"{market.lower()}-earnings-schedule:{code}", DAY, fetch))
363
436
  provider_events = [
364
437
  {
365
438
  "symbol": args.symbol,
@@ -370,13 +443,13 @@ def earnings_calendar(args):
370
443
  "date_kind": "provider_earnings_schedule",
371
444
  }
372
445
  for d in sections.get("dates", [])
373
- if d >= date.today().isoformat()
446
+ if d >= today
374
447
  ]
375
448
  if not stamp and not events:
376
449
  events = provider_events
377
450
  return {
378
451
  "symbol": args.symbol,
379
- "market": "HK",
452
+ "market": market,
380
453
  "source": "HKEX board-meeting notices"
381
454
  if any(r["confirmation"] == "official_board_meeting_notice" for r in events)
382
455
  else "yfinance earnings schedule",
@@ -387,11 +460,15 @@ def earnings_calendar(args):
387
460
  "forecasts_total": 0,
388
461
  "unverified_schedules": provider_events[: args.top] if stamp else [],
389
462
  "warnings": sections.get("warnings", [])
390
- + [
391
- "official dates are scheduled board meetings approving results, not actual disclosure dates; notice list may not be exhaustive",
392
- "provider-only schedules have unverified fiscal periods and are not assigned to requested report_date",
393
- ],
394
- "as_of": date.today().isoformat(),
463
+ + (
464
+ [
465
+ "official dates are scheduled board meetings approving results, not actual disclosure dates; notice list may not be exhaustive"
466
+ ]
467
+ if market == "HK"
468
+ else []
469
+ )
470
+ + ["provider-only schedules have unverified fiscal periods and are not assigned to requested report_date"],
471
+ "as_of": today,
395
472
  }
396
473
  if not stamp or stamp[5:] not in suffix:
397
474
  raise ValueError("report_date must be a quarter end for A-share earnings calendars")
@@ -495,8 +572,10 @@ def northbound_holdings(symbol, report_date=""):
495
572
  exchange = _cn_code(symbol)[:2]
496
573
  if exchange not in ("sh", "sz"):
497
574
  raise ValueError("Stock Connect holdings cover Shanghai/Shenzhen securities only")
498
- if report_date and (not iso(report_date) or iso(report_date)[5:] not in ("03-31", "06-30", "09-30", "12-31")):
499
- raise ValueError("report_date must be a quarter end")
575
+ if report_date:
576
+ report_date = iso(report_date)
577
+ if not report_date or report_date[5:] not in ("03-31", "06-30", "09-30", "12-31"):
578
+ raise ValueError("report_date must be a quarter end")
500
579
 
501
580
  def fetch():
502
581
  if exchange == "sh":
@@ -547,7 +626,7 @@ def northbound_holdings(symbol, report_date=""):
547
626
 
548
627
  stamp = report_date
549
628
  if not stamp:
550
- end = date(date.today().year, ((date.today().month - 1) // 3) * 3 + 1, 1) - timedelta(days=1)
629
+ end = date(_cn_now().date().year, ((_cn_now().date().month - 1) // 3) * 3 + 1, 1) - timedelta(days=1)
551
630
  for _ in range(2):
552
631
  candidate = end.isoformat()
553
632
  if query(candidate, "").get("data"):
@@ -566,7 +645,7 @@ def northbound_holdings(symbol, report_date=""):
566
645
  source = "SZSE quarterly Stock Connect holdings"
567
646
  if (
568
647
  not stamp
569
- or stamp > date.today().isoformat()
648
+ or stamp > _cn_now().date().isoformat()
570
649
  or (report_date and stamp != report_date)
571
650
  or shares is None
572
651
  or shares < 0
@@ -581,7 +660,7 @@ def northbound_holdings(symbol, report_date=""):
581
660
  "note": "exchange-disclosed aggregate Stock Connect quantity for this security; not a top-ten shareholder inference",
582
661
  }
583
662
 
584
- return cached(f"northbound-official:{symbol}:{report_date or date.today().isoformat()}", DAY, fetch)
663
+ return cached(f"northbound-official:{symbol}:{report_date or ''}", DAY, fetch)
585
664
 
586
665
 
587
666
  def shareholder_structure(args):
@@ -671,7 +750,7 @@ def shareholder_structure(args):
671
750
  def hk_dividend_ranking(report_date=""):
672
751
  import requests
673
752
 
674
- stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
753
+ stamp = iso(report_date) if report_date else f"{_cn_now().date().year - 1}-12-31"
675
754
  if not stamp or stamp[5:] != "12-31":
676
755
  raise ValueError("HK dividend ranking requires an annual year-end report_date")
677
756
 
@@ -768,7 +847,7 @@ def dividend_ranking(report_date="", market="A"):
768
847
  return hk_dividend_ranking(report_date)
769
848
  if market != "A":
770
849
  raise ValueError("dividend rankings cover A/HK only")
771
- stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
850
+ stamp = iso(report_date) if report_date else f"{_cn_now().date().year - 1}-12-31"
772
851
  if not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31"):
773
852
  raise ValueError("dividend report_date must be a quarter end")
774
853
  rows = dataset(f"dividend-ranking:{stamp}", lambda: ak.stock_fhps_em(date=stamp.replace("-", "")))
@@ -780,7 +859,8 @@ def dividend_ranking(report_date="", market="A"):
780
859
  {
781
860
  "symbol": str(r.get("代码", "")).zfill(6),
782
861
  "name": r.get("名称"),
783
- "dividend_yield": number(r.get("现金分红-股息率")),
862
+ # Eastmoney reports this ratio as a fraction (0.0101 = 1.01%).
863
+ "dividend_yield": round(number(r.get("现金分红-股息率")) * 100, 6),
784
864
  "ex_date": iso(r.get("除权除息日")),
785
865
  "announcement_date": iso(r.get("最新公告日期")),
786
866
  "status": r.get("方案进度"),
@@ -800,11 +880,12 @@ def dividends(args):
800
880
  result = dividend_ranking(args.report_date, getattr(args, "market", "A"))
801
881
  result["items"] = sorted(result["items"], key=lambda r: r["dividend_yield"], reverse=True)[: args.top]
802
882
  return result
803
- market, symbol = stock_identity(args.symbol)
883
+ market = detect_market(args.symbol)
884
+ market, symbol = (market, yf_symbol(args.symbol)) if market in YF_MARKETS else stock_identity(args.symbol)
804
885
  import akshare as ak
805
886
  from _subproc import run_tool
806
887
 
807
- today = date.today()
888
+ today = market_now(market).date()
808
889
  result = {
809
890
  "symbol": args.symbol,
810
891
  "market": market,
@@ -841,32 +922,47 @@ def dividends(args):
841
922
  import yfinance as yf
842
923
 
843
924
  sources = {}
844
- capture(
845
- sources,
846
- "calendar",
847
- lambda: dataset(f"hk-dividend-calendar:{symbol}", lambda: ak.stock_hk_dividend_payout_em(symbol=symbol)),
848
- )
849
- calendar = [
850
- {
851
- "ex_date": iso(r.get("除净日")),
852
- "payment_date": iso(r.get("发放日")),
853
- "announcement_date": iso(r.get("最新公告日期")),
854
- "plan": r.get("分红方案"),
855
- "fiscal_year": r.get("财政年度"),
856
- }
857
- for r in sources.get("calendar", [])
858
- ]
925
+ if market == "HK":
926
+ capture(
927
+ sources,
928
+ "calendar",
929
+ lambda: dataset(
930
+ f"hk-dividend-calendar:{symbol}", lambda: ak.stock_hk_dividend_payout_em(symbol=symbol)
931
+ ),
932
+ )
933
+ calendar = [
934
+ {
935
+ "ex_date": iso(r.get("除净日")),
936
+ "payment_date": iso(r.get("发放日")),
937
+ "announcement_date": iso(r.get("最新公告日期")),
938
+ "plan": r.get("分红方案"),
939
+ "fiscal_year": r.get("财政年度"),
940
+ }
941
+ for r in sources.get("calendar", [])
942
+ ]
943
+ ticker = yf.Ticker(_yf_hk_symbol(args.symbol))
944
+ else:
945
+ ticker = yf.Ticker(symbol)
946
+ capture(sources, "calendar", lambda: ticker.calendar)
947
+ upcoming = sources.get("calendar") or {}
948
+ calendar = [
949
+ {
950
+ "ex_date": iso(upcoming.get("Ex-Dividend Date")),
951
+ "payment_date": iso(upcoming.get("Dividend Date")),
952
+ }
953
+ ]
954
+ if not calendar[0]["ex_date"]:
955
+ calendar = []
859
956
  if args.mode == "calendar":
860
957
  if sources.get("warnings"):
861
- raise ValueError("HK dividend calendar unavailable")
958
+ raise ValueError(f"{market} dividend calendar unavailable")
862
959
  return {
863
960
  "symbol": args.symbol,
864
961
  "market": market,
865
- "source": "eastmoney",
962
+ "source": "eastmoney" if market == "HK" else "yfinance",
866
963
  "as_of": today.isoformat(),
867
964
  "calendar": [r for r in calendar if r.get("ex_date") and r["ex_date"] > today.isoformat()],
868
965
  }
869
- ticker = yf.Ticker(_yf_hk_symbol(args.symbol))
870
966
 
871
967
  def cash_history():
872
968
  raw = ticker.dividends
@@ -877,17 +973,17 @@ def dividends(args):
877
973
  )
878
974
  return frame.reset_index()
879
975
 
880
- capture(sources, "cash", lambda: dataset(f"hk-dividend-cash:{symbol}", cash_history))
976
+ capture(sources, "cash", lambda: dataset(f"{market.lower()}-dividend-cash:{symbol}", cash_history))
881
977
  capture(sources, "quote", lambda: ticker.info)
882
978
  paid = sources.get("cash", [])
883
979
  info = sources.get("quote") or {}
884
980
  if sources.get("warnings"):
885
981
  result["warnings"] = sources["warnings"]
886
982
  if not paid and not calendar:
887
- raise ValueError("HK dividend sources unavailable")
983
+ raise ValueError(f"{market} dividend sources unavailable")
888
984
  events = [
889
985
  {
890
- "ex_date": iso(r.get("Date")),
986
+ "ex_date": market_date(r.get("Date"), market),
891
987
  "cash_per_share": number(r.get("cash_per_share")),
892
988
  "currency": r.get("currency") or info.get("currency"),
893
989
  "status": "paid",
@@ -895,7 +991,11 @@ def dividends(args):
895
991
  for r in paid
896
992
  ]
897
993
  price = number(info.get("currentPrice") or info.get("regularMarketPrice"))
898
- result.update(source="yfinance cash / eastmoney calendar", currency=info.get("currency"), price=price)
994
+ result.update(
995
+ source="yfinance cash / eastmoney calendar" if market == "HK" else "yfinance",
996
+ currency=info.get("currency"),
997
+ price=price,
998
+ )
899
999
  result["calendar"] = [r for r in calendar if r["ex_date"] and r["ex_date"] > today.isoformat()]
900
1000
  cutoff = (today - timedelta(days=365.25 * args.years)).isoformat()
901
1001
  events = sorted(
@@ -1052,15 +1152,15 @@ def etf_basket(symbol):
1052
1152
  "SHOWTYPE": "JSON",
1053
1153
  "CATALOGID": "sgshqd",
1054
1154
  "txtJCorDH": symbol,
1055
- "txtStart": (date.today() - timedelta(days=30)).isoformat(),
1056
- "txtEnd": date.today().isoformat(),
1155
+ "txtStart": (_cn_now().date() - timedelta(days=30)).isoformat(),
1156
+ "txtEnd": _cn_now().date().isoformat(),
1057
1157
  },
1058
1158
  headers={"Referer": "https://www.szse.cn/"},
1059
1159
  timeout=20,
1060
1160
  )
1061
1161
  response.raise_for_status()
1062
1162
  dates = re.findall(rf"pcf_{re.escape(symbol)}_(\d{{8}})", json.dumps(response.json()))
1063
- dates = [d for d in dates if iso(d) and iso(d) <= date.today().isoformat()]
1163
+ dates = [d for d in dates if iso(d) and iso(d) <= _cn_now().date().isoformat()]
1064
1164
  if not dates:
1065
1165
  raise ValueError("no published SZSE PCF found")
1066
1166
  response = requests.get(
@@ -1083,7 +1183,7 @@ def etf_basket(symbol):
1083
1183
  if (
1084
1184
  fund_code != symbol
1085
1185
  or not stamp
1086
- or stamp > date.today().isoformat()
1186
+ or stamp > _cn_now().date().isoformat()
1087
1187
  or not unit
1088
1188
  or unit <= 0
1089
1189
  or count != len(components)
@@ -1141,7 +1241,7 @@ def etf_basket(symbol):
1141
1241
  "basis": "complete published creation/redemption basket, not actual fund holdings; quantities per creation unit, rates are fractions",
1142
1242
  }
1143
1243
 
1144
- return cached(f"etf-basket:{symbol}:{date.today().isoformat()}", DAY, fetch)
1244
+ return cached(f"etf-basket:{symbol}", DAY, fetch)
1145
1245
 
1146
1246
 
1147
1247
  def fund_disclosed_equities(symbol):
@@ -1208,7 +1308,7 @@ def fund_disclosed_equities(symbol):
1208
1308
  }
1209
1309
  raise ValueError("requested semiannual/annual equity report not available")
1210
1310
 
1211
- end = date(date.today().year, ((date.today().month - 1) // 6) * 6 + 1, 1) - timedelta(days=1)
1311
+ end = date(_cn_now().date().year, ((_cn_now().date().month - 1) // 6) * 6 + 1, 1) - timedelta(days=1)
1212
1312
  requested = end.isoformat()
1213
1313
  for _ in range(2):
1214
1314
  stamp = end.isoformat()
@@ -1227,20 +1327,28 @@ def etf_details(args):
1227
1327
  symbol = _cn_code(args.symbol)[2:]
1228
1328
  if detect_market(args.symbol) != "A" or not normalize_stock_code(symbol)["is_etf"] or not 10 <= args.days <= 252:
1229
1329
  raise ValueError("ETF details requires an A-share ETF code and days in 10..252")
1330
+ benchmark = (args.benchmark or "").strip()
1331
+ if suffixed := re.fullmatch(r"(\d{6})\.(SH|SZ)", benchmark, re.I):
1332
+ benchmark = suffixed[2].lower() + suffixed[1]
1333
+ if benchmark and not re.fullmatch(
1334
+ r"(?i)(sh|sz)?\d{6}|H\d{5}|93\d{4}|\^?(?!(sh|sz)\d)[A-Z][A-Z0-9.=-]{0,14}", benchmark
1335
+ ):
1336
+ raise ValueError("benchmark must be an index/ETF code such as sh000300, 399006, 000300.SH, H30269 or ^NDX")
1230
1337
  result = {
1231
1338
  "symbol": symbol,
1232
1339
  "market": "A",
1233
1340
  "source": "eastmoney",
1234
1341
  "holdings_basis": "latest disclosed fund portfolio, not a complete live creation/redemption basket",
1235
1342
  }
1236
- end = date.today()
1343
+ end = _cn_now().date()
1237
1344
  start = end - timedelta(days=args.days * 2)
1345
+ # akshare 1.20.41 renamed fund_etf_fund_info_em; py3.10 is capped below 1.20.40 and keeps the old name
1238
1346
  capture(
1239
1347
  result,
1240
1348
  "nav_history",
1241
1349
  lambda: dataset(
1242
- f"etf-nav:{symbol}:{args.days}",
1243
- lambda: ak.fund_etf_fund_info_em(
1350
+ f"etf-nav:{symbol}:{args.days}:{end.isoformat()}",
1351
+ lambda: (getattr(ak, "fund_exchange_nav_hist_em", None) or ak.fund_etf_fund_info_em)(
1244
1352
  fund=symbol, start_date=start.strftime("%Y%m%d"), end_date=end.strftime("%Y%m%d")
1245
1353
  ),
1246
1354
  ),
@@ -1310,13 +1418,30 @@ def etf_details(args):
1310
1418
  capture(result, "basket", lambda: etf_basket(symbol))
1311
1419
  if getattr(args, "include_full_holdings", False):
1312
1420
  capture(result, "disclosed_equity_report", lambda: fund_disclosed_equities(symbol))
1313
- if args.benchmark:
1314
- benchmark = "sh" + args.benchmark if args.benchmark in INDEX_NAMES else args.benchmark
1315
- benchmark_rows = run_tool("stock_data.py", ["kline", benchmark, "--count", str(args.days + 5)])
1421
+ if benchmark:
1422
+ if re.fullmatch(r"H\d{5}|93\d{4}", benchmark.upper()):
1423
+ benchmark = code = benchmark.upper()
1424
+ capture(
1425
+ result,
1426
+ "benchmark_history",
1427
+ lambda: dataset(
1428
+ f"csi-close:{code}:{args.days}:{end.isoformat()}",
1429
+ lambda: _csi_hist(ak)(
1430
+ symbol=code, start_date=start.strftime("%Y%m%d"), end_date=end.strftime("%Y%m%d")
1431
+ ),
1432
+ ),
1433
+ )
1434
+ history = result.pop("benchmark_history", [])
1435
+ benchmark_rows = [{"date": iso(r.get("日期")), "close": number(r.get("收盘"))} for r in history]
1436
+ else:
1437
+ if re.fullmatch(r"\d{6}", benchmark):
1438
+ benchmark = ("sz" if benchmark.startswith(("399", "15", "16")) else "sh") + benchmark
1439
+ code = benchmark[2:] if re.fullmatch(r"(?i)(sh|sz)\d{6}", benchmark) else ""
1440
+ benchmark = benchmark.lower() if code else benchmark
1441
+ benchmark_rows = run_tool("stock_data.py", ["kline", benchmark, "--count", str(args.days + 5)])
1316
1442
  result["tracking_error"] = tracking_error(nav, benchmark_rows if isinstance(benchmark_rows, list) else [])
1317
1443
  result["tracking_error"]["benchmark"] = benchmark
1318
- if benchmark.lower().startswith(("sh", "sz")):
1319
- code = benchmark[2:]
1444
+ if code:
1320
1445
  capture(
1321
1446
  result,
1322
1447
  "benchmark_constituents",
@@ -1360,15 +1485,122 @@ ANNOUNCEMENT_CATEGORIES = {
1360
1485
  "inquiry": ("", "问询"),
1361
1486
  "dividend": ("category_qyfpxzcs_szsh", ""),
1362
1487
  }
1488
+ HK_ANNOUNCEMENT_CATEGORIES = {
1489
+ "forecast": r"Profit Warning|Positive Profit Alert|Inside Information.*Profit",
1490
+ "annual": r"Final Results|Annual Report",
1491
+ "interim": r"Interim Results|Interim/Half-Year Report",
1492
+ "quarterly": r"Quarterly Results",
1493
+ "issuance": r"Issue of Securities|Placing|Rights Issue|Open Offer|Subscription",
1494
+ "dividend": r"Dividend",
1495
+ }
1496
+
1497
+
1498
+ def hk_announcements(args, symbol):
1499
+ import requests
1500
+
1501
+ if args.category != "all" and args.category not in HK_ANNOUNCEMENT_CATEGORIES:
1502
+ raise ValueError("HK announcements support all/forecast/annual/interim/quarterly/issuance/dividend")
1503
+ end = date.fromisoformat(args.end_date) if args.end_date else market_now("HK").date()
1504
+ start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1505
+ if start > end or not 1 <= args.top <= 500:
1506
+ raise ValueError("start_date must not exceed end_date and top must be in 1..500")
1507
+ response = requests.get(
1508
+ "https://www1.hkexnews.hk/search/prefix.do",
1509
+ params={"callback": "callback", "lang": "EN", "type": "A", "name": symbol, "market": "SEHK"},
1510
+ timeout=20,
1511
+ )
1512
+ response.raise_for_status()
1513
+ stocks = json.loads(re.sub(r"^\s*callback\(|\);?\s*$", "", response.text)).get("stockInfo", [])
1514
+ stock = next((row for row in stocks if row.get("code") == symbol), None)
1515
+ if not stock:
1516
+ raise ValueError("stock not found in HKEXnews directory")
1517
+ response = requests.get(
1518
+ "https://www1.hkexnews.hk/search/titleSearchServlet.do",
1519
+ params={
1520
+ "sortDir": 0,
1521
+ "sortByOptions": "DateTime",
1522
+ "category": 0,
1523
+ "market": "SEHK",
1524
+ "stockId": stock["stockId"],
1525
+ "documentType": -1,
1526
+ "fromDate": start.strftime("%Y%m%d"),
1527
+ "toDate": end.strftime("%Y%m%d"),
1528
+ "title": "",
1529
+ "searchType": 0,
1530
+ "t1code": -2,
1531
+ "t2Gcode": -2,
1532
+ "t2code": -2,
1533
+ # shortcut: one 500-row page; narrow the date range when truncated.
1534
+ "rowRange": 500,
1535
+ "lang": "E",
1536
+ },
1537
+ timeout=20,
1538
+ )
1539
+ response.raise_for_status()
1540
+ data = response.json()
1541
+ items = json.loads(data.get("result") or "[]")
1542
+ rows = []
1543
+ for row in items:
1544
+ kind = unescape(re.sub(r"<[^>]+>", " ", row.get("LONG_TEXT") or row.get("SHORT_TEXT") or "")).strip()
1545
+ title = unescape(re.sub(r"<[^>]+>", " ", row.get("TITLE") or "")).strip()
1546
+ # One announcement can carry several headlines (e.g. Final Results + Dividend); match any of them.
1547
+ matches = [
1548
+ key for key, pattern in HK_ANNOUNCEMENT_CATEGORIES.items() if re.search(pattern, f"{kind} {title}", re.I)
1549
+ ]
1550
+ inferred = args.category if args.category in matches else next(iter(matches), "other")
1551
+ path = row.get("FILE_LINK") or ""
1552
+ if args.category != "all" and inferred != args.category or not path.startswith("/listedco/"):
1553
+ continue
1554
+ rows.append(
1555
+ {
1556
+ "title": title,
1557
+ "date": datetime.strptime(row["DATE_TIME"], "%d/%m/%Y %H:%M").date().isoformat(),
1558
+ "category": inferred,
1559
+ "pdf_url": f"https://www1.hkexnews.hk{path}",
1560
+ "type": kind,
1561
+ }
1562
+ )
1563
+ total = int(data.get("recordCnt") or len(items))
1564
+ return {
1565
+ "symbol": args.symbol,
1566
+ "market": "HK",
1567
+ "source": "hkexnews",
1568
+ "start_date": start.isoformat(),
1569
+ "end_date": end.isoformat(),
1570
+ "total": total if args.category == "all" else len(rows),
1571
+ "total_basis": "provider_record_count" if args.category == "all" else "matched_in_loaded_rows",
1572
+ "announcements": rows[: args.top],
1573
+ "truncated": total > len(items) or len(rows) > args.top,
1574
+ "body_extracted": False,
1575
+ "requested_category": args.category,
1576
+ }
1363
1577
 
1364
1578
 
1365
1579
  def announcements(args):
1366
1580
  import requests
1367
1581
 
1582
+ if detect_market(args.symbol) == "US":
1583
+ import sec_edgar
1584
+
1585
+ if args.symbol.isdigit():
1586
+ # Bare digits are an unsuffixed HK code as often as a CIK; only CIK-prefixed numbers reach SEC.
1587
+ raise ValueError("numeric symbols need a CIK prefix (CIK320193) or HK .HK suffix (00700.HK)")
1588
+ end = date.fromisoformat(args.end_date) if args.end_date else market_now("US").date()
1589
+ start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1590
+ if start > end or not 1 <= args.top <= 500:
1591
+ raise ValueError("start_date must not exceed end_date and top must be in 1..500")
1592
+ symbol = (
1593
+ re.sub(r"^CIK", "", args.symbol, flags=re.I)
1594
+ if re.fullmatch(r"(?i)CIK[0-9]{1,10}", args.symbol)
1595
+ else args.symbol
1596
+ )
1597
+ return sec_edgar.filings(symbol, args.category, start, end, args.top)
1368
1598
  market, symbol = stock_identity(args.symbol)
1599
+ if market == "HK":
1600
+ return hk_announcements(args, symbol)
1369
1601
  if market != "A" or not 1 <= args.top <= 500 or args.category not in ANNOUNCEMENT_CATEGORIES:
1370
- raise ValueError("announcements require an A-share stock, valid category and top in 1..500")
1371
- end = date.fromisoformat(args.end_date) if args.end_date else date.today()
1602
+ raise ValueError("announcements require an A-share or US stock, valid category and top in 1..500")
1603
+ end = date.fromisoformat(args.end_date) if args.end_date else _cn_now().date()
1372
1604
  start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1373
1605
  if start > end:
1374
1606
  raise ValueError("start_date must not exceed end_date")