stock-analysis-plugin 0.2.11 → 0.2.13

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 (54) hide show
  1. package/README.md +234 -382
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +132 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +647 -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 +493 -0
  16. package/skills/bull-trend/SKILL.md +2 -2
  17. package/skills/bull-trend/references/fat-tails.md +76 -3
  18. package/skills/bull-trend/scripts/tail_analysis.py +92 -3
  19. package/skills/event-driven/SKILL.md +2 -2
  20. package/skills/growth-quality/SKILL.md +1 -1
  21. package/skills/market-review/SKILL.md +1 -0
  22. package/skills/stock-analysis/SKILL.md +12 -7
  23. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  24. package/skills/stock-screener/SKILL.md +1 -1
  25. package/skills/strategy-backtest/SKILL.md +1 -1
  26. package/tools/_cache.py +13 -0
  27. package/tools/_subproc.py +46 -0
  28. package/tools/alert_rules.py +2 -2
  29. package/tools/backtest.py +3 -3
  30. package/tools/capabilities.py +33 -9
  31. package/tools/cli_budgets.json +1 -0
  32. package/tools/credit_data.py +293 -0
  33. package/tools/diagnostics.py +3 -4
  34. package/tools/gather.py +2 -6
  35. package/tools/import_parser.py +3 -4
  36. package/tools/lixinger.py +119 -27
  37. package/tools/market_regime.py +5 -2
  38. package/tools/market_review.py +5 -6
  39. package/tools/name_resolver.py +45 -33
  40. package/tools/report_renderer.py +3 -3
  41. package/tools/requirements.txt +5 -4
  42. package/tools/risk_screening.py +3 -2
  43. package/tools/screener.py +41 -30
  44. package/tools/search_intel.py +79 -10
  45. package/tools/sec_edgar.py +268 -1
  46. package/tools/sec_holders.py +6 -0
  47. package/tools/signal_tracker.py +5 -5
  48. package/tools/stateless_analysis.py +132 -19
  49. package/tools/stock_data.py +1020 -817
  50. package/tools/tiaa_disclosures.py +4 -0
  51. package/tools/tool_schemas.json +2734 -0
  52. package/tools/trading_calendar.py +65 -30
  53. package/tools/value_data.py +423 -175
  54. 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,19 @@ 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 (
23
+ _A_INDEX_RE,
24
+ _cn_code,
25
+ _cn_now,
26
+ _em_datacenter,
27
+ _yf_hk_symbol,
28
+ detect_market,
29
+ normalize_stock_code,
30
+ )
31
+ from trading_calendar import _MARKET_TZ, market_now
32
+
33
+ YF_MARKETS = ("US", "JP", "KR", "TW")
23
34
 
24
35
 
25
36
  def records(frame):
@@ -51,6 +62,24 @@ def capture(result, key, fetch):
51
62
  result.setdefault("warnings", []).append(f"{key}: unavailable ({type(exc).__name__})")
52
63
 
53
64
 
65
+ def yf_symbol(symbol):
66
+ market = detect_market(symbol)
67
+ if market == "HK":
68
+ return _yf_hk_symbol(symbol)
69
+ if market not in YF_MARKETS or symbol.startswith("^"):
70
+ raise ValueError("a listed stock symbol is required")
71
+ if market == "US" and not re.fullmatch(r"[A-Za-z][A-Za-z0-9.-]{0,14}", symbol):
72
+ raise ValueError("a listed stock symbol is required (HK codes need .HK)") # "" / "00700" fall back to US
73
+ return symbol.upper().replace(".", "-") if market == "US" else symbol.upper()
74
+
75
+
76
+ def market_date(value, market):
77
+ parsed = pd.to_datetime(value, errors="coerce")
78
+ if pd.notna(parsed) and parsed.tzinfo is not None:
79
+ parsed = parsed.tz_convert(_MARKET_TZ["CN" if market == "A" else market])
80
+ return parsed.date().isoformat() if pd.notna(parsed) else None
81
+
82
+
54
83
  def stock_identity(symbol):
55
84
  market = detect_market(symbol)
56
85
  if _A_INDEX_RE.fullmatch(symbol):
@@ -81,42 +110,91 @@ def valuation_summary(history, field):
81
110
  }
82
111
 
83
112
 
113
+ def as_of(events, day):
114
+ """Latest event filed on or before day (events sorted by filed)."""
115
+ found = None
116
+ for event in events:
117
+ if event["filed"] > day:
118
+ break
119
+ found = event
120
+ return found
121
+
122
+
123
+ def us_valuation_history(args):
124
+ import sec_edgar
125
+ import yfinance as yf
126
+
127
+ symbol = yf_symbol(args.symbol)
128
+ facts = sec_edgar.valuation_facts(symbol)
129
+ ticker = yf.Ticker(symbol)
130
+ start = (market_now("US").date() - pd.DateOffset(years=args.years)).date()
131
+ # Close is split-adjusted to today's share basis; scale filed share counts by splits after their as-of date.
132
+ closes = ticker.history(start=start.isoformat(), auto_adjust=False)["Close"].dropna()
133
+ if closes.empty:
134
+ raise ValueError("US price history unavailable")
135
+ closes = closes.resample("W-FRI").last().dropna() # weekly samples keep 10-year output bounded
136
+ splits = {market_date(stamp, "US"): float(ratio) for stamp, ratio in ticker.splits.items() if ratio > 0}
137
+ events = {key: sorted(facts[key], key=lambda e: e["filed"]) for key in ("ttm_net_income", "equity", "shares")}
138
+ history = []
139
+ for stamp, close in closes.items():
140
+ day = market_date(stamp, "US")
141
+ shares, income, equity = (as_of(events[key], day) for key in ("shares", "ttm_net_income", "equity"))
142
+ if not shares:
143
+ continue
144
+ factor = float(np.prod([ratio for split_day, ratio in splits.items() if split_day > shares["end"]]))
145
+ cap = float(close) * shares["val"] * factor
146
+ history.append(
147
+ {
148
+ "date": day,
149
+ "pe_ttm": round(cap / income["val"], 4) if income and income["val"] else None,
150
+ "pb": round(cap / equity["val"], 4) if equity and equity["val"] else None,
151
+ }
152
+ )
153
+ if not history:
154
+ raise ValueError("no US valuation history available")
155
+ return {
156
+ "symbol": args.symbol,
157
+ "market": "US",
158
+ "source": "sec_companyfacts+yfinance",
159
+ "requested_years": args.years,
160
+ "sampling": "weekly",
161
+ "share_basis": facts["share_basis"],
162
+ "history": history,
163
+ "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
164
+ "warnings": [
165
+ "Derived: market cap = weekly close x latest SEC-filed share count; PE uses TTM NetIncomeLoss attributable to parent, "
166
+ "PB uses StockholdersEquity, each effective from its filing date. "
167
+ "Multi-class issuers sum all classes at one class price."
168
+ ],
169
+ }
170
+
171
+
84
172
  def valuation_history(args):
85
173
  import akshare as ak
86
174
 
87
- market, symbol = stock_identity(args.symbol)
88
175
  if not 1 <= args.years <= 10:
89
- raise ValueError("valuation history requires an A/HK symbol and years in 1..10")
176
+ raise ValueError("years must be in 1..10")
177
+ if detect_market(args.symbol) == "US":
178
+ return us_valuation_history(args)
179
+ market, symbol = stock_identity(args.symbol)
90
180
  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"
181
+ if os.environ.get("LIXINGER_TOKEN"):
182
+ try:
183
+ import lixinger
184
+
185
+ history = lixinger.valuation_history("cn" if market == "A" else "hk", symbol, args.years)
186
+ return {
187
+ "symbol": args.symbol,
188
+ "market": market,
189
+ "source": "lixinger",
190
+ "requested_years": args.years,
191
+ "history": history,
192
+ "metrics": {field: valuation_summary(history, field) for field in ("pe_ttm", "pb")},
193
+ }
194
+ except Exception as e:
195
+ warning = f"Lixinger {market} unavailable: {error_message(e)}; Baidu history used without mixing sources"
196
+ elif market == "HK":
197
+ warning = "LIXINGER_TOKEN not configured; HK history limited to available Baidu data"
120
198
  fetch = ak.stock_zh_valuation_baidu if market == "A" else ak.stock_hk_valuation_baidu
121
199
  period = "近一年" if args.years == 1 else "近三年" if args.years <= 3 else "近五年" if args.years <= 5 else "近十年"
122
200
  if market == "HK" and args.years > 3:
@@ -133,7 +211,7 @@ def valuation_history(args):
133
211
  ),
134
212
  )
135
213
  merged = {}
136
- cutoff = (date.today() - timedelta(days=365.25 * args.years)).isoformat()
214
+ cutoff = (_cn_now().date() - timedelta(days=365.25 * args.years)).isoformat()
137
215
  for field in ("pe_ttm", "pb"):
138
216
  for row in series.get(field, []):
139
217
  stamp = iso(row.get("date"))
@@ -160,28 +238,22 @@ INDEX_NAMES = {
160
238
  }
161
239
 
162
240
 
241
+ def _csi_hist(ak):
242
+ # akshare 1.20.44 renamed it; py3.10 stays below 1.20.40 with the old name.
243
+ return getattr(ak, "index_hist_csindex", None) or ak.stock_zh_index_hist_csindex
244
+
245
+
163
246
  def lixinger_index_history(code, start, end):
164
- import requests
247
+ import lixinger
165
248
 
166
249
  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,
250
+ data = lixinger.post(
251
+ "cn/index/fundamental",
252
+ {"stockCodes": [code], "startDate": start, "endDate": end, "metricsList": ["pe_ttm.mcw", "pb.mcw"]},
177
253
  )
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
254
  rows = [
183
255
  {"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", [])
256
+ for r in data
185
257
  if r.get("stockCode") == code
186
258
  ]
187
259
  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 +273,7 @@ def index_valuation(args):
201
273
  raise ValueError("years must be in 1..10")
202
274
  result = {"symbol": code, "name": name, "source": "legulegu", "requested_years": args.years}
203
275
  merged = {}
204
- cutoff = (pd.Timestamp(date.today()) - pd.DateOffset(years=args.years)).date().isoformat()
276
+ cutoff = (pd.Timestamp(_cn_now().date()) - pd.DateOffset(years=args.years)).date().isoformat()
205
277
  for field, fn, column in [("pe_ttm", ak.stock_index_pe_lg, "滚动市盈率"), ("pb", ak.stock_index_pb_lg, "市净率")]:
206
278
  section = {}
207
279
  capture(
@@ -211,7 +283,7 @@ def index_valuation(args):
211
283
  )
212
284
  for row in section.get("rows", []):
213
285
  stamp = iso(row.get("日期"))
214
- if stamp and cutoff <= stamp <= date.today().isoformat():
286
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat():
215
287
  merged.setdefault(stamp, {"date": stamp})[field] = number(row.get(column))
216
288
  result.setdefault("warnings", []).extend(section.get("warnings", []))
217
289
  if not any(number(r.get("pe_ttm")) is not None for r in merged.values()) and re.fullmatch(
@@ -223,24 +295,27 @@ def index_valuation(args):
223
295
  "history",
224
296
  lambda: dataset(
225
297
  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")
298
+ lambda: _csi_hist(ak)(
299
+ symbol=code, start_date=cutoff.replace("-", ""), end_date=_cn_now().date().strftime("%Y%m%d")
228
300
  ),
229
301
  ),
230
302
  )
231
303
  for row in section.get("history", []):
232
304
  stamp = iso(row.get("日期"))
233
305
  pe = number(row.get("滚动市盈率"))
234
- if stamp and cutoff <= stamp <= date.today().isoformat() and pe is not None:
306
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat() and pe is not None:
235
307
  merged.setdefault(stamp, {"date": stamp})["pe_ttm"] = pe
236
308
  capture(
237
309
  section,
238
310
  "recent",
239
- lambda: dataset(f"csi-valuation:{code}", lambda: ak.stock_zh_index_value_csindex(symbol=code)),
311
+ lambda: dataset(
312
+ f"csi-valuation:{code}",
313
+ lambda: (getattr(ak, "index_value_csindex", None) or ak.stock_zh_index_value_csindex)(symbol=code),
314
+ ),
240
315
  )
241
316
  for row in section.get("recent", []):
242
317
  stamp = iso(row.get("日期"))
243
- if stamp and cutoff <= stamp <= date.today().isoformat():
318
+ if stamp and cutoff <= stamp <= _cn_now().date().isoformat():
244
319
  merged.setdefault(stamp, {"date": stamp}).update(
245
320
  pe=number(row.get("市盈率1")), dividend_yield=number(row.get("股息率1"))
246
321
  )
@@ -258,9 +333,9 @@ def index_valuation(args):
258
333
  missing = [field for field in ("pe_ttm", "pb") if field not in result["metric_sources"]]
259
334
  if missing and os.environ.get("LIXINGER_TOKEN") and re.fullmatch(r"\d{6}|H\d{5}", code, re.I):
260
335
  section = {}
261
- capture(section, "rows", lambda: lixinger_index_history(code, cutoff, date.today().isoformat()))
336
+ capture(section, "rows", lambda: lixinger_index_history(code, cutoff, _cn_now().date().isoformat()))
262
337
  for row in section.get("rows", []):
263
- if row["date"] and cutoff <= row["date"] <= date.today().isoformat():
338
+ if row["date"] and cutoff <= row["date"] <= _cn_now().date().isoformat():
264
339
  for field in missing:
265
340
  if row[field] is not None:
266
341
  merged.setdefault(row["date"], {"date": row["date"]})[field] = row[field]
@@ -328,38 +403,41 @@ def hk_board_meetings(board):
328
403
 
329
404
 
330
405
  def earnings_calendar(args):
331
- import akshare as ak
332
-
333
406
  stamp = iso(args.report_date)
334
- suffix = {"03-31": "一季", "06-30": "半年报", "09-30": "三季", "12-31": "年报"}
335
407
  if not 1 <= args.top <= 500 or (args.report_date and not stamp):
336
408
  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":
409
+ market = detect_market(args.symbol) if args.symbol else "A"
410
+ if market in ("KR", "TW"):
411
+ raise ValueError("earnings calendar covers A/HK/US/JP only")
412
+ if market in ("HK", "US", "JP"):
338
413
  import yfinance as yf
339
414
 
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"])
415
+ code = yf_symbol(args.symbol)
416
+ today = market_now(market).date().isoformat()
417
+ sections, events = {}, []
418
+ if market == "HK":
419
+ hk_code = stock_identity(args.symbol)[1]
420
+ for board in ("main", "gem"):
421
+ capture(sections, board, lambda board=board: hk_board_meetings(board))
422
+ events = [
423
+ r
424
+ for board in ("main", "gem")
425
+ for r in sections.get(board, [])
426
+ if r["symbol"] == hk_code + ".HK"
427
+ and r["scheduled_date"] >= today
428
+ and (not stamp or r["report_date"] == stamp)
429
+ ]
430
+ events = list({(r["scheduled_date"], r["purpose"], r["report_date"]): r for r in events}.values())
431
+ events.sort(key=lambda r: r["scheduled_date"])
354
432
 
355
433
  def fetch():
356
- frame = yf.Ticker(_yf_hk_symbol(args.symbol)).get_earnings_dates(limit=12)
434
+ frame = yf.Ticker(code).get_earnings_dates(limit=12)
357
435
  if frame is None:
358
- raise ValueError("HK earnings schedule unavailable")
359
- return sorted({iso(d) for d in frame.index if iso(d)})
436
+ raise ValueError(f"{market} earnings schedule unavailable")
437
+ return sorted({market_date(d, market) for d in frame.index if market_date(d, market)})
360
438
 
361
439
  if not events:
362
- capture(sections, "dates", lambda: cached(f"hk-earnings-schedule:{_yf_hk_symbol(args.symbol)}", DAY, fetch))
440
+ capture(sections, "dates", lambda: cached(f"{market.lower()}-earnings-schedule:{code}", DAY, fetch))
363
441
  provider_events = [
364
442
  {
365
443
  "symbol": args.symbol,
@@ -370,13 +448,13 @@ def earnings_calendar(args):
370
448
  "date_kind": "provider_earnings_schedule",
371
449
  }
372
450
  for d in sections.get("dates", [])
373
- if d >= date.today().isoformat()
451
+ if d >= today
374
452
  ]
375
453
  if not stamp and not events:
376
454
  events = provider_events
377
455
  return {
378
456
  "symbol": args.symbol,
379
- "market": "HK",
457
+ "market": market,
380
458
  "source": "HKEX board-meeting notices"
381
459
  if any(r["confirmation"] == "official_board_meeting_notice" for r in events)
382
460
  else "yfinance earnings schedule",
@@ -387,43 +465,48 @@ def earnings_calendar(args):
387
465
  "forecasts_total": 0,
388
466
  "unverified_schedules": provider_events[: args.top] if stamp else [],
389
467
  "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(),
468
+ + (
469
+ [
470
+ "official dates are scheduled board meetings approving results, not actual disclosure dates; notice list may not be exhaustive"
471
+ ]
472
+ if market == "HK"
473
+ else []
474
+ )
475
+ + ["provider-only schedules have unverified fiscal periods and are not assigned to requested report_date"],
476
+ "as_of": today,
395
477
  }
396
- if not stamp or stamp[5:] not in suffix:
478
+ if not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31"):
397
479
  raise ValueError("report_date must be a quarter end for A-share earnings calendars")
398
480
  symbol = ""
399
481
  if args.symbol:
400
482
  market, symbol = stock_identity(args.symbol)
401
483
  if market != "A":
402
484
  raise ValueError("earnings calendar covers A shares only")
403
- result = {"report_date": stamp, "source": "cninfo/eastmoney"}
404
- capture(
405
- result,
406
- "disclosures",
407
- lambda: dataset(
408
- f"disclosure:{stamp}",
409
- lambda: ak.stock_report_disclosure(market="沪深京", period=stamp[:4] + suffix[stamp[5:]]),
410
- ),
411
- )
412
- capture(
413
- result, "forecasts", lambda: dataset(f"forecast:{stamp}", lambda: ak.stock_yjyg_em(date=stamp.replace("-", "")))
414
- )
485
+ result = {"report_date": stamp, "source": "eastmoney"}
486
+ # Server-side filter + limit: one page holds the requested rows, `count` the full total.
487
+ condition = f"(REPORT_DATE='{stamp}')" + (f'(SECURITY_CODE="{symbol}")' if symbol else "")
488
+ totals = {}
489
+ queries = {
490
+ "disclosures": ("RPT_PUBLIC_BS_APPOIN", "APPOINT_PUBLISH_DATE,SECURITY_CODE", "1,1"),
491
+ "forecasts": ("RPT_PUBLIC_OP_NEWPREDICT", "NOTICE_DATE,SECURITY_CODE", "-1,-1"),
492
+ }
493
+ for key, (report, sort, order) in queries.items():
494
+
495
+ def fetch(report=report, sort=sort, order=order, key=key):
496
+ totals[key], rows = _em_datacenter(report, condition, sort, args.top, order)
497
+ return rows
498
+
499
+ capture(result, key, fetch)
415
500
  for key in ("disclosures", "forecasts"):
416
- rows = result.get(key, [])
417
- if symbol:
418
- rows = [r for r in rows if str(r.get("股票代码", "")).zfill(6) == symbol]
419
501
  output = []
420
- for row in rows:
421
- item = {"symbol": str(row.get("股票代码", "")).zfill(6), "name": row.get("股票简称")}
502
+ for row in result.get(key, []):
503
+ item = {"symbol": str(row.get("SECURITY_CODE", "")).zfill(6), "name": row.get("SECURITY_NAME_ABBR")}
422
504
  if key == "disclosures":
423
- revised = [iso(row.get(c)) for c in ("首次预约", "初次变更", "二次变更", "三次变更")]
505
+ columns = ("FIRST_APPOINT_DATE", "FIRST_CHANGE_DATE", "SECOND_CHANGE_DATE", "THIRD_CHANGE_DATE")
506
+ revised = [iso(row.get(c)) for c in columns]
424
507
  item.update(
425
508
  scheduled_date=next((d for d in reversed(revised) if d), None),
426
- actual_date=iso(row.get("实际披露")),
509
+ actual_date=iso(row.get("ACTUAL_PUBLISH_DATE")),
427
510
  original_scheduled_date=revised[0],
428
511
  scheduled_date_revisions=[
429
512
  {"revision": i, "scheduled_date": d} for i, d in enumerate(revised[1:], 1) if d
@@ -431,16 +514,16 @@ def earnings_calendar(args):
431
514
  )
432
515
  else:
433
516
  item.update(
434
- announcement_date=iso(row.get("公告日期")),
435
- forecast_type=row.get("预告类型"),
436
- indicator=row.get("预测指标"),
437
- forecast_value=number(row.get("预测数值")),
438
- change_pct=number(row.get("业绩变动幅度")),
439
- reason=row.get("业绩变动原因"),
517
+ announcement_date=iso(row.get("NOTICE_DATE")),
518
+ forecast_type=row.get("PREDICT_TYPE"),
519
+ indicator=row.get("PREDICT_FINANCE"),
520
+ forecast_value=number(row.get("FORECAST_JZ")),
521
+ change_pct=number(row.get("INCREASE_JZ")),
522
+ reason=row.get("CHANGE_REASON_EXPLAIN"),
440
523
  )
441
524
  output.append(item)
442
- result[key + "_total"] = len(output)
443
- result[key] = output[: args.top]
525
+ result[key + "_total"] = totals.get(key, 0)
526
+ result[key] = output
444
527
  if result.get("warnings") and not result["disclosures"] and not result["forecasts"]:
445
528
  raise ValueError("earnings calendar sources unavailable")
446
529
  return result
@@ -495,8 +578,10 @@ def northbound_holdings(symbol, report_date=""):
495
578
  exchange = _cn_code(symbol)[:2]
496
579
  if exchange not in ("sh", "sz"):
497
580
  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")
581
+ if report_date:
582
+ report_date = iso(report_date)
583
+ if not report_date or report_date[5:] not in ("03-31", "06-30", "09-30", "12-31"):
584
+ raise ValueError("report_date must be a quarter end")
500
585
 
501
586
  def fetch():
502
587
  if exchange == "sh":
@@ -547,7 +632,7 @@ def northbound_holdings(symbol, report_date=""):
547
632
 
548
633
  stamp = report_date
549
634
  if not stamp:
550
- end = date(date.today().year, ((date.today().month - 1) // 3) * 3 + 1, 1) - timedelta(days=1)
635
+ end = date(_cn_now().date().year, ((_cn_now().date().month - 1) // 3) * 3 + 1, 1) - timedelta(days=1)
551
636
  for _ in range(2):
552
637
  candidate = end.isoformat()
553
638
  if query(candidate, "").get("data"):
@@ -566,7 +651,7 @@ def northbound_holdings(symbol, report_date=""):
566
651
  source = "SZSE quarterly Stock Connect holdings"
567
652
  if (
568
653
  not stamp
569
- or stamp > date.today().isoformat()
654
+ or stamp > _cn_now().date().isoformat()
570
655
  or (report_date and stamp != report_date)
571
656
  or shares is None
572
657
  or shares < 0
@@ -581,7 +666,7 @@ def northbound_holdings(symbol, report_date=""):
581
666
  "note": "exchange-disclosed aggregate Stock Connect quantity for this security; not a top-ten shareholder inference",
582
667
  }
583
668
 
584
- return cached(f"northbound-official:{symbol}:{report_date or date.today().isoformat()}", DAY, fetch)
669
+ return cached(f"northbound-official:{symbol}:{report_date or ''}", DAY, fetch)
585
670
 
586
671
 
587
672
  def shareholder_structure(args):
@@ -671,7 +756,7 @@ def shareholder_structure(args):
671
756
  def hk_dividend_ranking(report_date=""):
672
757
  import requests
673
758
 
674
- stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
759
+ stamp = iso(report_date) if report_date else f"{_cn_now().date().year - 1}-12-31"
675
760
  if not stamp or stamp[5:] != "12-31":
676
761
  raise ValueError("HK dividend ranking requires an annual year-end report_date")
677
762
 
@@ -761,32 +846,43 @@ def hk_dividend_ranking(report_date=""):
761
846
  return cached(f"hk-dividend-ranking:{stamp}", DAY, fetch)
762
847
 
763
848
 
764
- def dividend_ranking(report_date="", market="A"):
765
- import akshare as ak
849
+ def dividend_ranking(report_date="", market="A", top=500, codes=None):
850
+ """Implemented cash-dividend plans ranked by yield, sorted and limited server-side.
766
851
 
852
+ `codes` (A only) restricts the query to those stocks — the screener asks only for its candidates."""
767
853
  if market == "HK":
768
854
  return hk_dividend_ranking(report_date)
769
855
  if market != "A":
770
856
  raise ValueError("dividend rankings cover A/HK only")
771
- stamp = iso(report_date) if report_date else f"{date.today().year - 1}-12-31"
857
+ stamp = iso(report_date) if report_date else f"{_cn_now().date().year - 1}-12-31"
772
858
  if not stamp or stamp[5:] not in ("03-31", "06-30", "09-30", "12-31"):
773
859
  raise ValueError("dividend report_date must be a quarter end")
774
- rows = dataset(f"dividend-ranking:{stamp}", lambda: ak.stock_fhps_em(date=stamp.replace("-", "")))
860
+ base = f"(REPORT_DATE='{stamp}')(ASSIGN_PROGRESS=\"实施分配\")"
861
+ if codes is None:
862
+ queries = [(base, top)]
863
+ else:
864
+ codes = [c for c in codes if re.fullmatch(r"\d{6}", str(c))]
865
+ chunks = [codes[i : i + 200] for i in range(0, len(codes), 200)]
866
+ queries = [(base + "(SECURITY_CODE in (" + ",".join(f'"{c}"' for c in chunk) + "))", 500) for chunk in chunks]
867
+ rows = []
868
+ for condition, size in queries:
869
+ rows += _em_datacenter("RPT_SHAREBONUS_DET", condition, "DIVIDENT_RATIO", size)[1]
775
870
  return {
776
871
  "report_date": stamp,
777
872
  "source": "eastmoney",
778
873
  "yield_basis": "provider report-period cash dividend yield, percent",
779
874
  "items": [
780
875
  {
781
- "symbol": str(r.get("代码", "")).zfill(6),
782
- "name": r.get("名称"),
783
- "dividend_yield": number(r.get("现金分红-股息率")),
784
- "ex_date": iso(r.get("除权除息日")),
785
- "announcement_date": iso(r.get("最新公告日期")),
786
- "status": r.get("方案进度"),
876
+ "symbol": str(r.get("SECURITY_CODE", "")).zfill(6),
877
+ "name": r.get("SECURITY_NAME_ABBR"),
878
+ # Eastmoney reports this ratio as a fraction (0.0101 = 1.01%).
879
+ "dividend_yield": round(number(r.get("DIVIDENT_RATIO")) * 100, 6),
880
+ "ex_date": iso(r.get("EX_DIVIDEND_DATE")),
881
+ "announcement_date": iso(r.get("NOTICE_DATE")),
882
+ "status": r.get("ASSIGN_PROGRESS"),
787
883
  }
788
884
  for r in rows
789
- if r.get("方案进度") == "实施分配" and number(r.get("现金分红-股息率")) is not None
885
+ if number(r.get("DIVIDENT_RATIO")) is not None
790
886
  ],
791
887
  }
792
888
 
@@ -797,14 +893,15 @@ def dividends(args):
797
893
  if args.mode == "ranking":
798
894
  if args.symbol:
799
895
  raise ValueError("ranking covers all A shares; omit symbol")
800
- result = dividend_ranking(args.report_date, getattr(args, "market", "A"))
896
+ result = dividend_ranking(args.report_date, getattr(args, "market", "A"), top=args.top)
801
897
  result["items"] = sorted(result["items"], key=lambda r: r["dividend_yield"], reverse=True)[: args.top]
802
898
  return result
803
- market, symbol = stock_identity(args.symbol)
899
+ market = detect_market(args.symbol)
900
+ market, symbol = (market, yf_symbol(args.symbol)) if market in YF_MARKETS else stock_identity(args.symbol)
804
901
  import akshare as ak
805
902
  from _subproc import run_tool
806
903
 
807
- today = date.today()
904
+ today = market_now(market).date()
808
905
  result = {
809
906
  "symbol": args.symbol,
810
907
  "market": market,
@@ -841,32 +938,47 @@ def dividends(args):
841
938
  import yfinance as yf
842
939
 
843
940
  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
- ]
941
+ if market == "HK":
942
+ capture(
943
+ sources,
944
+ "calendar",
945
+ lambda: dataset(
946
+ f"hk-dividend-calendar:{symbol}", lambda: ak.stock_hk_dividend_payout_em(symbol=symbol)
947
+ ),
948
+ )
949
+ calendar = [
950
+ {
951
+ "ex_date": iso(r.get("除净日")),
952
+ "payment_date": iso(r.get("发放日")),
953
+ "announcement_date": iso(r.get("最新公告日期")),
954
+ "plan": r.get("分红方案"),
955
+ "fiscal_year": r.get("财政年度"),
956
+ }
957
+ for r in sources.get("calendar", [])
958
+ ]
959
+ ticker = yf.Ticker(_yf_hk_symbol(args.symbol))
960
+ else:
961
+ ticker = yf.Ticker(symbol)
962
+ capture(sources, "calendar", lambda: ticker.calendar)
963
+ upcoming = sources.get("calendar") or {}
964
+ calendar = [
965
+ {
966
+ "ex_date": iso(upcoming.get("Ex-Dividend Date")),
967
+ "payment_date": iso(upcoming.get("Dividend Date")),
968
+ }
969
+ ]
970
+ if not calendar[0]["ex_date"]:
971
+ calendar = []
859
972
  if args.mode == "calendar":
860
973
  if sources.get("warnings"):
861
- raise ValueError("HK dividend calendar unavailable")
974
+ raise ValueError(f"{market} dividend calendar unavailable")
862
975
  return {
863
976
  "symbol": args.symbol,
864
977
  "market": market,
865
- "source": "eastmoney",
978
+ "source": "eastmoney" if market == "HK" else "yfinance",
866
979
  "as_of": today.isoformat(),
867
980
  "calendar": [r for r in calendar if r.get("ex_date") and r["ex_date"] > today.isoformat()],
868
981
  }
869
- ticker = yf.Ticker(_yf_hk_symbol(args.symbol))
870
982
 
871
983
  def cash_history():
872
984
  raw = ticker.dividends
@@ -877,17 +989,17 @@ def dividends(args):
877
989
  )
878
990
  return frame.reset_index()
879
991
 
880
- capture(sources, "cash", lambda: dataset(f"hk-dividend-cash:{symbol}", cash_history))
992
+ capture(sources, "cash", lambda: dataset(f"{market.lower()}-dividend-cash:{symbol}", cash_history))
881
993
  capture(sources, "quote", lambda: ticker.info)
882
994
  paid = sources.get("cash", [])
883
995
  info = sources.get("quote") or {}
884
996
  if sources.get("warnings"):
885
997
  result["warnings"] = sources["warnings"]
886
998
  if not paid and not calendar:
887
- raise ValueError("HK dividend sources unavailable")
999
+ raise ValueError(f"{market} dividend sources unavailable")
888
1000
  events = [
889
1001
  {
890
- "ex_date": iso(r.get("Date")),
1002
+ "ex_date": market_date(r.get("Date"), market),
891
1003
  "cash_per_share": number(r.get("cash_per_share")),
892
1004
  "currency": r.get("currency") or info.get("currency"),
893
1005
  "status": "paid",
@@ -895,7 +1007,11 @@ def dividends(args):
895
1007
  for r in paid
896
1008
  ]
897
1009
  price = number(info.get("currentPrice") or info.get("regularMarketPrice"))
898
- result.update(source="yfinance cash / eastmoney calendar", currency=info.get("currency"), price=price)
1010
+ result.update(
1011
+ source="yfinance cash / eastmoney calendar" if market == "HK" else "yfinance",
1012
+ currency=info.get("currency"),
1013
+ price=price,
1014
+ )
899
1015
  result["calendar"] = [r for r in calendar if r["ex_date"] and r["ex_date"] > today.isoformat()]
900
1016
  cutoff = (today - timedelta(days=365.25 * args.years)).isoformat()
901
1017
  events = sorted(
@@ -1052,15 +1168,15 @@ def etf_basket(symbol):
1052
1168
  "SHOWTYPE": "JSON",
1053
1169
  "CATALOGID": "sgshqd",
1054
1170
  "txtJCorDH": symbol,
1055
- "txtStart": (date.today() - timedelta(days=30)).isoformat(),
1056
- "txtEnd": date.today().isoformat(),
1171
+ "txtStart": (_cn_now().date() - timedelta(days=30)).isoformat(),
1172
+ "txtEnd": _cn_now().date().isoformat(),
1057
1173
  },
1058
1174
  headers={"Referer": "https://www.szse.cn/"},
1059
1175
  timeout=20,
1060
1176
  )
1061
1177
  response.raise_for_status()
1062
1178
  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()]
1179
+ dates = [d for d in dates if iso(d) and iso(d) <= _cn_now().date().isoformat()]
1064
1180
  if not dates:
1065
1181
  raise ValueError("no published SZSE PCF found")
1066
1182
  response = requests.get(
@@ -1083,7 +1199,7 @@ def etf_basket(symbol):
1083
1199
  if (
1084
1200
  fund_code != symbol
1085
1201
  or not stamp
1086
- or stamp > date.today().isoformat()
1202
+ or stamp > _cn_now().date().isoformat()
1087
1203
  or not unit
1088
1204
  or unit <= 0
1089
1205
  or count != len(components)
@@ -1141,7 +1257,7 @@ def etf_basket(symbol):
1141
1257
  "basis": "complete published creation/redemption basket, not actual fund holdings; quantities per creation unit, rates are fractions",
1142
1258
  }
1143
1259
 
1144
- return cached(f"etf-basket:{symbol}:{date.today().isoformat()}", DAY, fetch)
1260
+ return cached(f"etf-basket:{symbol}", DAY, fetch)
1145
1261
 
1146
1262
 
1147
1263
  def fund_disclosed_equities(symbol):
@@ -1208,7 +1324,7 @@ def fund_disclosed_equities(symbol):
1208
1324
  }
1209
1325
  raise ValueError("requested semiannual/annual equity report not available")
1210
1326
 
1211
- end = date(date.today().year, ((date.today().month - 1) // 6) * 6 + 1, 1) - timedelta(days=1)
1327
+ end = date(_cn_now().date().year, ((_cn_now().date().month - 1) // 6) * 6 + 1, 1) - timedelta(days=1)
1212
1328
  requested = end.isoformat()
1213
1329
  for _ in range(2):
1214
1330
  stamp = end.isoformat()
@@ -1227,20 +1343,28 @@ def etf_details(args):
1227
1343
  symbol = _cn_code(args.symbol)[2:]
1228
1344
  if detect_market(args.symbol) != "A" or not normalize_stock_code(symbol)["is_etf"] or not 10 <= args.days <= 252:
1229
1345
  raise ValueError("ETF details requires an A-share ETF code and days in 10..252")
1346
+ benchmark = (args.benchmark or "").strip()
1347
+ if suffixed := re.fullmatch(r"(\d{6})\.(SH|SZ)", benchmark, re.I):
1348
+ benchmark = suffixed[2].lower() + suffixed[1]
1349
+ if benchmark and not re.fullmatch(
1350
+ r"(?i)(sh|sz)?\d{6}|H\d{5}|93\d{4}|\^?(?!(sh|sz)\d)[A-Z][A-Z0-9.=-]{0,14}", benchmark
1351
+ ):
1352
+ raise ValueError("benchmark must be an index/ETF code such as sh000300, 399006, 000300.SH, H30269 or ^NDX")
1230
1353
  result = {
1231
1354
  "symbol": symbol,
1232
1355
  "market": "A",
1233
1356
  "source": "eastmoney",
1234
1357
  "holdings_basis": "latest disclosed fund portfolio, not a complete live creation/redemption basket",
1235
1358
  }
1236
- end = date.today()
1359
+ end = _cn_now().date()
1237
1360
  start = end - timedelta(days=args.days * 2)
1361
+ # akshare 1.20.41 renamed fund_etf_fund_info_em; py3.10 is capped below 1.20.40 and keeps the old name
1238
1362
  capture(
1239
1363
  result,
1240
1364
  "nav_history",
1241
1365
  lambda: dataset(
1242
- f"etf-nav:{symbol}:{args.days}",
1243
- lambda: ak.fund_etf_fund_info_em(
1366
+ f"etf-nav:{symbol}:{args.days}:{end.isoformat()}",
1367
+ lambda: (getattr(ak, "fund_exchange_nav_hist_em", None) or ak.fund_etf_fund_info_em)(
1244
1368
  fund=symbol, start_date=start.strftime("%Y%m%d"), end_date=end.strftime("%Y%m%d")
1245
1369
  ),
1246
1370
  ),
@@ -1310,13 +1434,30 @@ def etf_details(args):
1310
1434
  capture(result, "basket", lambda: etf_basket(symbol))
1311
1435
  if getattr(args, "include_full_holdings", False):
1312
1436
  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)])
1437
+ if benchmark:
1438
+ if re.fullmatch(r"H\d{5}|93\d{4}", benchmark.upper()):
1439
+ benchmark = code = benchmark.upper()
1440
+ capture(
1441
+ result,
1442
+ "benchmark_history",
1443
+ lambda: dataset(
1444
+ f"csi-close:{code}:{args.days}:{end.isoformat()}",
1445
+ lambda: _csi_hist(ak)(
1446
+ symbol=code, start_date=start.strftime("%Y%m%d"), end_date=end.strftime("%Y%m%d")
1447
+ ),
1448
+ ),
1449
+ )
1450
+ history = result.pop("benchmark_history", [])
1451
+ benchmark_rows = [{"date": iso(r.get("日期")), "close": number(r.get("收盘"))} for r in history]
1452
+ else:
1453
+ if re.fullmatch(r"\d{6}", benchmark):
1454
+ benchmark = ("sz" if benchmark.startswith(("399", "15", "16")) else "sh") + benchmark
1455
+ code = benchmark[2:] if re.fullmatch(r"(?i)(sh|sz)\d{6}", benchmark) else ""
1456
+ benchmark = benchmark.lower() if code else benchmark
1457
+ benchmark_rows = run_tool("stock_data.py", ["kline", benchmark, "--count", str(args.days + 5)])
1316
1458
  result["tracking_error"] = tracking_error(nav, benchmark_rows if isinstance(benchmark_rows, list) else [])
1317
1459
  result["tracking_error"]["benchmark"] = benchmark
1318
- if benchmark.lower().startswith(("sh", "sz")):
1319
- code = benchmark[2:]
1460
+ if code:
1320
1461
  capture(
1321
1462
  result,
1322
1463
  "benchmark_constituents",
@@ -1360,15 +1501,122 @@ ANNOUNCEMENT_CATEGORIES = {
1360
1501
  "inquiry": ("", "问询"),
1361
1502
  "dividend": ("category_qyfpxzcs_szsh", ""),
1362
1503
  }
1504
+ HK_ANNOUNCEMENT_CATEGORIES = {
1505
+ "forecast": r"Profit Warning|Positive Profit Alert|Inside Information.*Profit",
1506
+ "annual": r"Final Results|Annual Report",
1507
+ "interim": r"Interim Results|Interim/Half-Year Report",
1508
+ "quarterly": r"Quarterly Results",
1509
+ "issuance": r"Issue of Securities|Placing|Rights Issue|Open Offer|Subscription",
1510
+ "dividend": r"Dividend",
1511
+ }
1512
+
1513
+
1514
+ def hk_announcements(args, symbol):
1515
+ import requests
1516
+
1517
+ if args.category != "all" and args.category not in HK_ANNOUNCEMENT_CATEGORIES:
1518
+ raise ValueError("HK announcements support all/forecast/annual/interim/quarterly/issuance/dividend")
1519
+ end = date.fromisoformat(args.end_date) if args.end_date else market_now("HK").date()
1520
+ start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1521
+ if start > end or not 1 <= args.top <= 500:
1522
+ raise ValueError("start_date must not exceed end_date and top must be in 1..500")
1523
+ response = requests.get(
1524
+ "https://www1.hkexnews.hk/search/prefix.do",
1525
+ params={"callback": "callback", "lang": "EN", "type": "A", "name": symbol, "market": "SEHK"},
1526
+ timeout=20,
1527
+ )
1528
+ response.raise_for_status()
1529
+ stocks = json.loads(re.sub(r"^\s*callback\(|\);?\s*$", "", response.text)).get("stockInfo", [])
1530
+ stock = next((row for row in stocks if row.get("code") == symbol), None)
1531
+ if not stock:
1532
+ raise ValueError("stock not found in HKEXnews directory")
1533
+ response = requests.get(
1534
+ "https://www1.hkexnews.hk/search/titleSearchServlet.do",
1535
+ params={
1536
+ "sortDir": 0,
1537
+ "sortByOptions": "DateTime",
1538
+ "category": 0,
1539
+ "market": "SEHK",
1540
+ "stockId": stock["stockId"],
1541
+ "documentType": -1,
1542
+ "fromDate": start.strftime("%Y%m%d"),
1543
+ "toDate": end.strftime("%Y%m%d"),
1544
+ "title": "",
1545
+ "searchType": 0,
1546
+ "t1code": -2,
1547
+ "t2Gcode": -2,
1548
+ "t2code": -2,
1549
+ # shortcut: one 500-row page; narrow the date range when truncated.
1550
+ "rowRange": 500,
1551
+ "lang": "E",
1552
+ },
1553
+ timeout=20,
1554
+ )
1555
+ response.raise_for_status()
1556
+ data = response.json()
1557
+ items = json.loads(data.get("result") or "[]")
1558
+ rows = []
1559
+ for row in items:
1560
+ kind = unescape(re.sub(r"<[^>]+>", " ", row.get("LONG_TEXT") or row.get("SHORT_TEXT") or "")).strip()
1561
+ title = unescape(re.sub(r"<[^>]+>", " ", row.get("TITLE") or "")).strip()
1562
+ # One announcement can carry several headlines (e.g. Final Results + Dividend); match any of them.
1563
+ matches = [
1564
+ key for key, pattern in HK_ANNOUNCEMENT_CATEGORIES.items() if re.search(pattern, f"{kind} {title}", re.I)
1565
+ ]
1566
+ inferred = args.category if args.category in matches else next(iter(matches), "other")
1567
+ path = row.get("FILE_LINK") or ""
1568
+ if args.category != "all" and inferred != args.category or not path.startswith("/listedco/"):
1569
+ continue
1570
+ rows.append(
1571
+ {
1572
+ "title": title,
1573
+ "date": datetime.strptime(row["DATE_TIME"], "%d/%m/%Y %H:%M").date().isoformat(),
1574
+ "category": inferred,
1575
+ "pdf_url": f"https://www1.hkexnews.hk{path}",
1576
+ "type": kind,
1577
+ }
1578
+ )
1579
+ total = int(data.get("recordCnt") or len(items))
1580
+ return {
1581
+ "symbol": args.symbol,
1582
+ "market": "HK",
1583
+ "source": "hkexnews",
1584
+ "start_date": start.isoformat(),
1585
+ "end_date": end.isoformat(),
1586
+ "total": total if args.category == "all" else len(rows),
1587
+ "total_basis": "provider_record_count" if args.category == "all" else "matched_in_loaded_rows",
1588
+ "announcements": rows[: args.top],
1589
+ "truncated": total > len(items) or len(rows) > args.top,
1590
+ "body_extracted": False,
1591
+ "requested_category": args.category,
1592
+ }
1363
1593
 
1364
1594
 
1365
1595
  def announcements(args):
1366
1596
  import requests
1367
1597
 
1598
+ if detect_market(args.symbol) == "US":
1599
+ import sec_edgar
1600
+
1601
+ if args.symbol.isdigit():
1602
+ # Bare digits are an unsuffixed HK code as often as a CIK; only CIK-prefixed numbers reach SEC.
1603
+ raise ValueError("numeric symbols need a CIK prefix (CIK320193) or HK .HK suffix (00700.HK)")
1604
+ end = date.fromisoformat(args.end_date) if args.end_date else market_now("US").date()
1605
+ start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1606
+ if start > end or not 1 <= args.top <= 500:
1607
+ raise ValueError("start_date must not exceed end_date and top must be in 1..500")
1608
+ symbol = (
1609
+ re.sub(r"^CIK", "", args.symbol, flags=re.I)
1610
+ if re.fullmatch(r"(?i)CIK[0-9]{1,10}", args.symbol)
1611
+ else args.symbol
1612
+ )
1613
+ return sec_edgar.filings(symbol, args.category, start, end, args.top)
1368
1614
  market, symbol = stock_identity(args.symbol)
1615
+ if market == "HK":
1616
+ return hk_announcements(args, symbol)
1369
1617
  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()
1618
+ raise ValueError("announcements require an A-share or US stock, valid category and top in 1..500")
1619
+ end = date.fromisoformat(args.end_date) if args.end_date else _cn_now().date()
1372
1620
  start = date.fromisoformat(args.start_date) if args.start_date else end - timedelta(days=90)
1373
1621
  if start > end:
1374
1622
  raise ValueError("start_date must not exceed end_date")