hamuna-quant-cli 0.1.9__tar.gz → 0.1.11__tar.gz

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.9
+Version: 0.1.11
 Summary: Hamuna A 股回测 + 实盘统一 CLI (akquant 0.3.x). 替代 v1 自建 driver + QMT-style 策略规范.
 Author-email: Hamuna Team <team@hamuna.example>
 License: MIT

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/hamuna_quant_cli/__init__.py

@@ -12,4 +12,4 @@ server (13-key metrics schema). 全部走 akquant 0.3.x 引擎.
 """
 from __future__ import annotations
 
-__version__ = "0.1.9"
+__version__ = "0.1.11"

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/hamuna_quant_cli/__main__.py

@@ -331,9 +331,22 @@ def cmd_commit(args) -> int:
     bridge_server 扫描执行; hamuna-quant-cli 下单走 bridge_server HTTP.
     bundle = 4 文件 (strategy + result + config + params). multipart params 字段
     = 整个 params.json 内容 (ADR-0025, desktop 实盘配置源).
+
+    Round 18.62 P0-1: 新增 step 1.5 replay diff gate — `--replay-result` 必填,
+    与 `--result` 算 sharpe diff, 超阈值 (HAMUNA_REPLAY_GATE_PCT 缺省 0.20) → exit 5.
+    server `UpdateStrategyResult` handler 二次校验防绕过.
+
+    Round 18.62 P1-1: 新增 step 1.4 version bump — `GET /strategies/{id}` 拿
+    `latest_version` (无 → "0.0.0"); 默认 patch 自动 bump (`0.0.0 → 0.0.1`),
+    `--major` → `X+1.0.0`, `--minor` → `X.Y+1.0`. `--major + --minor` 互斥.
+    server handler 强校验 semver 格式 + 严格递增; PUT body 必含 `version`.
     """
     from . import runtime
+    from .runtime.server_client import ServerError
+    import io
     import json
+    import os
+    import re
     import tarfile
 
     sid = args.strategy_id
@@ -354,11 +367,47 @@ def cmd_commit(args) -> int:
     if params_path and not params_path.exists():
         print(f"params.json 不存在: {params_path} (--params 可选)", file=sys.stderr)
         return 2
+    # Round 18.62 P0-1: replay_result.json 必填 (除非 --skip-replay-gate qa 通道).
+    replay_path = Path(args.replay_result) if args.replay_result else None
+    if not args.skip_replay_gate:
+        if replay_path is None:
+            print("ERROR: P0-1: 必须传 --replay-result, 先跑 live run --broker replay 拿 metrics "
+                  "(或 --skip-replay-gate qa 通道)", file=sys.stderr)
+            return 2
+        if not replay_path.exists():
+            print(f"replay_result.json 不存在: {args.replay_result}", file=sys.stderr)
+            return 2
+
+    # ----- Round 18.62 P1-1 step 1.4: version bump -----
+    # cli 先 GET /strategies/{id} 拿 latest_version (无 → "0.0.0"); 默认 patch 自动 bump,
+    # --major → X+1.0.0, --minor → X.Y+1.0. 互斥校验防呆. server 二次校验 (semver 格式 +
+    # 严格递增) 防绕过. PUT body 必含 version (P1-1 server 强校验).
+    if args.major and args.minor:
+        print("ERROR: --major 与 --minor 互斥, 选一个或不传 (默认 patch)", file=sys.stderr)
+        return 2
+    try:
+        strat = runtime.server_client.get_strategy(sid)
+        latest = (strat or {}).get("latest_version") or "0.0.0"
+    except ServerError:
+        latest = "0.0.0"  # 404 / 401 等都 fallback, 新策略首次 commit
+    if not re.fullmatch(r"\d+\.\d+\.\d+", latest):
+        print(f"ERROR: server latest_version '{latest}' 不是合法 semver (X.Y.Z), "
+              f"请手动清理 strategies.latest_version 后重试", file=sys.stderr)
+        return 2
+    major, minor, patch = (int(x) for x in latest.split("."))
+    if args.major:
+        new_version = f"{major + 1}.0.0"
+    elif args.minor:
+        new_version = f"{major}.{minor + 1}.0"
+    else:
+        new_version = f"{major}.{minor}.{patch + 1}"
+    print(f"=== Step 1.4/3: P1-1 version bump ({latest} → {new_version}) ===",
+          file=sys.stderr)
 
     bundle_out = Path(args.bundle_out) if args.bundle_out else Path(f"runs/{sid}/bundle.tar.gz")
     bundle_out.parent.mkdir(parents=True, exist_ok=True)
 
-    print("=== Step 1/3: 打包 bundle (strategy + result + config + params) ===",
+    print("=== Step 1/3: 打包 bundle (strategy + result + config + params + replay + version) ===",
           file=sys.stderr)
     with tarfile.open(bundle_out, "w:gz") as tar:
         tar.add(strategy_path, arcname=strategy_path.name)
@@ -367,16 +416,60 @@ def cmd_commit(args) -> int:
             tar.add(cfg_path, arcname=cfg_path.name)
         if params_path:
             tar.add(params_path, arcname=params_path.name)
+        # Round 18.62 P0-1: replay_result.json 也打进去, 方便回溯 / 审计.
+        if replay_path:
+            tar.add(replay_path, arcname=replay_path.name)
+        # Round 18.62 P1-1: version.json 内存写, audit 用 (server 不读, 仅本地回溯).
+        ver_bytes = json.dumps({"version": new_version}, ensure_ascii=False).encode("utf-8")
+        ver_info = tarfile.TarInfo(name="version.json")
+        ver_info.size = len(ver_bytes)
+        tar.addfile(ver_info, io.BytesIO(ver_bytes))
     print(f"  ✓ bundle = {bundle_out} ({bundle_out.stat().st_size} bytes)", file=sys.stderr)
 
-    print("=== Step 2/3: PUT /strategies/:id/result (metrics) ===", file=sys.stderr)
+    # ----- Round 18.62 P0-1 step 1.5: replay diff gate -----
+    # 必在 step 2 (PUT) 之前 — gate fail 后 step 2-3 都不跑, 不留半上传状态.
+    replay_metrics: dict | None = None
+    if not args.skip_replay_gate:
+        try:
+            bt = json.loads(result_path.read_text(encoding="utf-8"))
+            rp = json.loads(replay_path.read_text(encoding="utf-8"))  # type: ignore[union-attr]
+        except json.JSONDecodeError as e:
+            print(f"  ✗ result/replay JSON 解析失败: {e}", file=sys.stderr)
+            return 2
+        bt_sharpe = float(bt.get("metrics", {}).get("sharpe", 0.0))
+        rp_sharpe = float(rp.get("metrics", {}).get("sharpe", 0.0))
+        diff_pct = abs(rp_sharpe - bt_sharpe) / max(abs(bt_sharpe), 0.01)
+        try:
+            threshold = float(os.environ.get("HAMUNA_REPLAY_GATE_PCT", "0.20"))
+        except ValueError:
+            threshold = 0.20
+        if diff_pct > threshold:
+            print(f"ERROR: replay gate diff={diff_pct:.2%} > {threshold:.0%} "
+                  f"(backtest.sharpe={bt_sharpe:.4f} vs replay.sharpe={rp_sharpe:.4f})",
+                  file=sys.stderr)
+            return 5
+        replay_metrics = {
+            "sharpe": rp_sharpe,
+            "total_return": float(rp.get("metrics", {}).get("total_return", 0.0)),
+            "win_rate": float(rp.get("metrics", {}).get("win_rate", 0.0)),
+            "trades": len(rp.get("trades", [])),
+            "diff_pct": diff_pct,
+            "run_at": (rp.get("period") or {}).get("end"),
+        }
+        print(f"  ✓ replay gate pass (diff={diff_pct:.2%} <= {threshold:.0%}, "
+              f"replay.sharpe={rp_sharpe:.4f})", file=sys.stderr)
+
+    print("=== Step 2/3: PUT /strategies/:id/result (metrics + replay_metrics + version) ===",
+          file=sys.stderr)
     try:
         result = json.loads(result_path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as e:
         print(f"  ✗ result.json 解析失败: {e}", file=sys.stderr)
         return 2
     try:
-        resp = runtime.server_client.upload_backtest_result(sid, result)
+        resp = runtime.server_client.upload_backtest_result(
+            sid, result, replay_metrics=replay_metrics, version=new_version,
+        )
     except runtime.server_client.ServerError as e:
         print(f"  ✗ 上传 metrics 失败: {e}", file=sys.stderr)
         return 4
@@ -943,6 +1036,18 @@ def build_parser() -> argparse.ArgumentParser:
     cm.add_argument("strategy_id", help="server 端 strategy_id")
     cm.add_argument("--strategy", help="akquant strategy .py 路径 (默认 <id>.py)")
     cm.add_argument("--result", required=True, help="metrics result.json 路径")
+    # Round 18.62 P0-1: replay gate. --replay-result 必填 (除非 --skip-replay-gate).
+    cm.add_argument("--replay-result", default=None,
+                    help="replay_result.json 路径 (P0-1 必填; 先跑 live run --broker replay 拿 metrics, "
+                         "或 --skip-replay-gate 跳过)")
+    cm.add_argument("--skip-replay-gate", action="store_true",
+                    help="[qa 临时] 跳过 replay diff gate (非 dev 默认)")
+    # Round 18.62 P1-1: version bump. 默认 patch 自动 (从 server latest_version +0.0.1),
+    # 显式 --major / --minor opt-in. 互斥.
+    cm.add_argument("--major", action="store_true",
+                    help="[P1-1] major bump (X+1.0.0); 跟 --minor 互斥")
+    cm.add_argument("--minor", action="store_true",
+                    help="[P1-1] minor bump (X.Y+1.0); 跟 --major 互斥")
     cm.add_argument("--config", help="config.json 路径")
     cm.add_argument("--params", default=None,
                     help="params.json 路径 (固定 schema; 整个内容作 multipart params 字段, desktop 实盘配置源)")

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/hamuna_quant_cli/live/runner.py

@@ -9,6 +9,7 @@
 from __future__ import annotations
 
 import sys
+import json  # Round 18.62 P0-1: replay metrics 落盘
 from pathlib import Path
 from typing import Any
 
@@ -216,19 +217,39 @@ def _build_instruments(symbols: list[str] | None, normalize: bool = False) -> li
 
     normalize=True: 裸码 → 带后缀 (replay 数据来自 prebuilt, stockCode 是 '600000.SH'
     形态, instrument symbol 必须一致才匹配 ReplayMarketGateway 的订阅过滤).
+
+    Round 18.59: 按 6 位代码前缀推断 AssetType — akquant 0.3.x AssetType 枚举没 ETF 也没 Bond,
+    510/511/512/515/159 (沪/深 ETF) → Fund; 113/127/128 (可转债) → Fund; 其他 6 位 → Stock.
+    之前硬写 AssetType.Stock 让 351 个 ETF 被 broker 内部按 asset_type 分流时丢弃 → universe=[].
+    ponytail: akquant 0.4.x 若新增 AssetType.ETF / AssetType.Bond 则此映射需重审.
     """
     if not symbols:
         return None
     # 延迟 import akquant — 让 loader 在 akquant 未装环境也能跑通
     from akquant import AssetType, Instrument
 
+    _ETF_PREFIXES = ("510", "511", "512", "515", "159")
+    _BOND_PREFIXES = ("113", "127", "128")  # 可转债 (沪 113 / 深 127 / 沪 128)
+
     def _sym(s: str) -> str:
         if normalize:
             from ..akquant_schema_adapter import normalize_symbol
             return normalize_symbol(s)
         return s
 
-    return [Instrument(symbol=_sym(s), asset_type=AssetType.Stock) for s in symbols if s.strip()]
+    def _asset_type(bare: str) -> Any:
+        # _sym 后可能是 6 位裸码或 600000.SH 形态 — 都按前 3 位判
+        code6 = bare.split(".")[0][-6:] if "." in bare else bare[-6:]
+        if not (len(code6) == 6 and code6.isdigit()):
+            return AssetType.Stock  # 非法 6 位 fallback, 不阻塞启动
+        pfx3 = code6[:3]
+        if pfx3.startswith(_ETF_PREFIXES):
+            return AssetType.Fund
+        if pfx3.startswith(_BOND_PREFIXES):
+            return AssetType.Fund
+        return AssetType.Stock
+
+    return [Instrument(symbol=_sym(s), asset_type=_asset_type(_sym(s))) for s in symbols if s.strip()]
 
 
 def _recent_real_bars(symbols: list[str], days: int = 30) -> tuple[Any, str]:
@@ -770,4 +791,45 @@ def run_live(
           f"market_broker={market_broker or '<single>'} "
           f"symbols={symbols or '<all>'} duration={duration}", flush=True)
     print(f"[info] gateway_options={gateway_options}", flush=True)
-    _akquant_run_live(**kwargs)
+    _akquant_run_live(**kwargs)
+
+    # ===== Round 18.62 P0-1: replay metrics 产出 =====
+    # live run 跑完后, 拿同一份 bars + strategy_cls 跑一次 mini-backtest 拿 metrics,
+    # 落 runs/{strategy_id}/replay_result.json (跟 cmd_run 同 13-key schema, to_hamuna_result).
+    # 用途: commiter cmd_commit --replay-result 拿此文件 vs 回测 result.json 算 sharpe diff.
+    # 仅 broker=replay 时跑 (其他 broker 真盘无意义, 也没 bars 数据).
+    if broker == "replay" and spec.mode == "class" and spec.strategy_cls is not None:
+        try:
+            from akquant import run_backtest as _akquant_run_backtest  # noqa: F401
+            from ..akquant_schema_adapter import to_hamuna_result
+            from datetime import datetime as _dt
+            # strategy_id 来自 run_live kwargs 顶层 (Round 18.42+ commiter 必传);
+            # 若没有 (裸 live run 调) 退到 /tmp/replay_result.json, 不污染 runs/.
+            strategy_id = kwargs.get("strategy_id") or "adhoc"
+            out_dir = Path("runs") / strategy_id
+            out_dir.mkdir(parents=True, exist_ok=True)
+            out_path = out_dir / "replay_result.json"
+            # 用 replay_bars_df + strategy_cls 跑 mini-backtest. 同一份数据 → 可比.
+            mini_kwargs = dict(kwargs)
+            mini_kwargs.pop("live", None)  # 防混入 live flag
+            # to_hamuna_result 需 akquant BacktestResult 对象; mini-backtest 走同一 strategy_cls
+            # + 同一份 bars, 拿 metrics 对象 → to_hamuna_result 落 13-key schema.
+            bt_result = _akquant_run_backtest(
+                strategy_cls=spec.strategy_cls,
+                bars=replay_bars_df,
+                initial_cash=initial_cash or 100000.0,
+            )
+            cfg = {"period": {"start": str(replay_bars_df['date'].min())[:10] if hasattr(replay_bars_df, 'columns') else "",
+                                "end": str(_dt.now().date())}}
+            result_dict = to_hamuna_result(bt_result, cfg)
+            out_path.write_text(json.dumps(result_dict, indent=2, ensure_ascii=False), encoding="utf-8")
+            m = result_dict.get("metrics", {})
+            print(f"[info] replay metrics: sharpe={m.get('sharpe'):.3f} "
+                  f"total_return={m.get('total_return', 0):.2%} trades={len(result_dict.get('trades', []))} "
+                  f"→ {out_path}", flush=True)
+        except ImportError:
+            # akquant 未装 / to_hamuna_result 不可用 — 跳过, 不阻塞 live run
+            print("[warn] P0-1: akquant / to_hamuna_result 未装, 跳过 replay metrics 产出", flush=True)
+        except Exception as e:
+            # mini-backtest 失败不致命 — live run 已成功, 只 warn
+            print(f"[warn] P0-1: replay metrics 产出失败 ({type(e).__name__}: {e}), 跳过", flush=True)

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/hamuna_quant_cli/runtime/server_client.py

@@ -72,14 +72,38 @@ def _api_call(method: str, path: str, body: dict | None = None) -> dict:
     return envelope
 
 
-def upload_backtest_result(strategy_id: str, result: dict) -> dict:
-    """PUT /api/v1/strategies/{id}/result → 上传 BacktestResult-shape dict.
+def upload_backtest_result(strategy_id: str, result: dict, replay_metrics: dict | None = None, version: str | None = None) -> dict:
+    """PUT /api/v1/strategies/{id}/result → 上传 BacktestResult-shape dict + 可选 replay_metrics + version.
 
     兼容 akquant_runner.run_akquant_backtest() 输出 (13 顶层 key + metrics 子 dict 15 key + ...),
     先做轻清洗: NaN/Inf → None (json 标准不允许), 后传给 server.
+
+    Round 18.62 P0-1: replay_metrics (Sharpe/TotalReturn/WinRate/Trades/DiffPct/RunAt) —
+    跟 result 平级, server handler 二次校验 diff 防绕过. None 时不传该 key (老调用方不破).
+    Round 18.62 P1-1: version (X.Y.Z semver) — cli 默认 patch 自动 bump (cmd_commit step 1.4
+    拿 server latest_version 算新 version), server handler 二次校验 semver 格式 + 严格递增.
+    老调用方 (无 version kwarg) → 不传该 key → server 422 (P1-1 强校验).
     """
     payload = _sanitize_for_json(result)
-    return _api_call('PUT', f'/api/v1/strategies/{strategy_id}/result', payload)
+    # P1-1 P0-1.1 ponytail: 无条件 wrap `{"result": ...}` 让 server 解析形状一致
+    # (即使 replay_metrics=None / version=None 也要 wrap, 防止 server handler 422 invalid shape).
+    # 此改动在 P1-1 同步实施, P0-1 Case F 已知问题修复.
+    body: dict = {"result": payload}
+    if replay_metrics is not None:
+        body["replay_metrics"] = _sanitize_for_json(replay_metrics)
+    if version is not None:
+        body["version"] = version
+    return _api_call('PUT', f'/api/v1/strategies/{strategy_id}/result', body)
+
+
+def get_strategy(strategy_id: str) -> dict:
+    """GET /api/v1/strategies/{id} → server DataValue (含 latest_version / result / versions[]).
+
+    Round 18.62 P1-1: cli 端 version auto-bump 需要 latest_version. 404 raise ServerError,
+    caller (cmd_commit) fallback "0.0.0" + patch bump. 返 dict (含 latest_version 字段);
+    若 server 返回 DataValue 是 dict 直接返, 是 None 也直接返让 caller 用 .get() 容错.
+    """
+    return _api_call('GET', f'/api/v1/strategies/{strategy_id}')
 
 
 def create_strategy(name: str, code: str = '', params: dict | None = None) -> dict:

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/hamuna_quant_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hamuna-quant-cli
-Version: 0.1.9
+Version: 0.1.11
 Summary: Hamuna A 股回测 + 实盘统一 CLI (akquant 0.3.x). 替代 v1 自建 driver + QMT-style 策略规范.
 Author-email: Hamuna Team <team@hamuna.example>
 License: MIT

{hamuna_quant_cli-0.1.9 → hamuna_quant_cli-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hamuna-quant-cli"
-version = "0.1.9"
+version = "0.1.11"
 description = "Hamuna A 股回测 + 实盘统一 CLI (akquant 0.3.x). 替代 v1 自建 driver + QMT-style 策略规范."
 readme = "hamuna_quant_cli/README.md"
 requires-python = ">=3.10"