hamuna-quant-cli 0.1.0.dev93__py3-none-any.whl

hamuna_quant_cli/_market_fallback.py

@@ -0,0 +1,82 @@
+"""hamuna_quant_cli._market_fallback — 内联最小 v1 market API 替代.
+
+为什么: 历史 v2 代码 `from strategy_cli.fundamental.data import market` 走 v1 skill
+(hamuna-strategy), pip install hamuna-quant-cli 后 v1 不可见 → ImportError.
+这里把 v1 market.get_market_data_ex 的"只 prebuilt parquet"小份实现搬过来,
+远程数据源 (容维 / Tushare 等) 留给 v1 skill 走.
+
+接口契约 (对齐 v1 market.get_market_data_ex):
+  get_market_data_ex(codes: list[str], period: str, start: str, end: str) -> dict[str, list[dict]]
+    codes: ['600000.SH', '000001.SZ']
+    period: '1d' (其他抛 NotImplementedError)
+    start/end: 'YYYYMMDD'
+    返: {sym: [{date|time, open, high, low, close, volume, ...}, ...]}
+
+内部走 prebuilt_resolver.resolve (pyarrow filter pushdown), 失败 → NotImplementedError
+提示用户先用 v1 skill 或自己下载 prebuilt parquet.
+
+Ponytail: 这里只覆盖 v1 的"日线 + prebuilt"路径; 多周期 / 实时行情仍走 v1.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def get_market_data_ex(
+    stock_code: list[str],
+    period: str,
+    start_time: str,
+    end_time: str,
+) -> dict[str, list[dict[str, Any]]]:
+    """v1 market API 兼容 shim: 只走 prebuilt parquet, 远程 API 不覆盖.
+
+    Args:
+      stock_code: 标的代码 list (e.g. ['600000.SH', '000001.SZ'])
+      period: '1d' (其他抛 NotImplementedError)
+      start_time / end_time: 'YYYYMMDD'
+
+    Returns:
+      {sym: [{date|time, open, high, low, close, volume, ...}, ...]}
+
+    Raises:
+      NotImplementedError: period 不是 '1d', 或 dataset 不存在
+      FileNotFoundError: prebuilt parquet 缺数据
+    """
+    if period != "1d":
+        raise NotImplementedError(
+            f"_market_fallback 仅支持 1d, period={period} 需走 v1 skill (hamuna-strategy)")
+
+    if not stock_code:
+        return {}
+
+    from .prebuilt_resolver import resolve
+
+    df, _src = resolve(list(stock_code), start_time, end_time, period="1d")
+    if df is None or df.empty:
+        # 与 v1 路径一致: 抛 FileNotFoundError, 让上层走"换 dataset / 离线导入"分支
+        raise FileNotFoundError(
+            f"未在 prebuilt dataset 找到 {stock_code} ({start_time}~{end_time}). "
+            f"先用 `hamuna_quant_cli dataset fetch --symbols ...` 下载或走 v1 skill "
+            f"(`hamuna-strategy`) 的容维 fallback.")
+
+    # df → v1 形状: {sym: [{date: int YYYYMMDD, open, high, low, close, volume}, ...]}
+    out: dict[str, list[dict[str, Any]]] = {}
+    for sym, sub in df.groupby("symbol", sort=False):
+        rows: list[dict[str, Any]] = []
+        for _, row in sub.iterrows():
+            ts = row["date"]
+            # ts: Timestamp → 'YYYYMMDD' int (对齐 v1 容维 market 输出)
+            if hasattr(ts, "strftime"):
+                date_int = int(ts.strftime("%Y%m%d"))
+            else:
+                date_int = int(str(ts)[:8].replace("-", ""))
+            rows.append({
+                "date": date_int,
+                "open": float(row["open"]),
+                "high": float(row["high"]),
+                "low": float(row["low"]),
+                "close": float(row["close"]),
+                "volume": float(row["volume"]),
+            })
+        out[str(sym)] = rows
+    return out

hamuna_quant_cli/_metrics_15.py

@@ -0,0 +1,342 @@
+"""hamuna-strategy-v2 单点 15 metric 实现 — 自有命名空间版本 (B2).
+
+来源: 原仓根 `hamuna_quant_cli/references/_metrics_15.py` (Phase B, 算法 frozen).
+本文件是 wholesale copy, 算法逐函数与原仓根一致 (B 重写不动数值层).
+迁移原因: v2 skill 未来独立分发, 必须自带 metrics 实现, 不依赖仓根
+hamuna_quant_cli (那是 Phase B 公用层, 非 skill 一部分).
+
+对齐保证:
+  - 算法逐函数复刻原仓根 _metrics_15
+  - NaN 纪律: NaN/null = 计算 bug, 不上抛. 安全 getter 缺失字段填 NaN.
+  - 单位: total_return/annual_return/volatility/sortino/calmar/var_95/...
+    全部"小数"形式 (0.05 = 5%), win_rate 0~1, profit_loss_ratio/profit_factor 比率.
+
+API:
+  compute_all(nav_curve, trades) -> dict[str, float]
+    含 benchmark_total_return=NaN, excess_return=NaN (akquant 单策略无自动基准).
+
+Ponytail ceiling: 本文件不暴露给仓根, 只供本包内 `hamuna_quant_cli.references.*`
+                  自引用. v1 driver (`skills/hamuna-strategy/strategy_cli/runtime/metrics.py`)
+                  是另一套独立实现, 数值层 < 1e-6 差异, 不可互换.
+"""
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from datetime import date as _date, datetime
+
+import numpy as np
+
+# hamuna metrics 15 keys (与 server model.BacktestResult 对齐)
+HAMUNA_METRICS_15 = frozenset({
+    'total_return', 'annual_return', 'sharpe', 'max_drawdown', 'volatility',
+    'win_rate', 'profit_loss_ratio', 'avg_holding_period',
+    'benchmark_total_return', 'excess_return',
+    'sortino', 'calmar', 'var_95', 'profit_factor',
+    'annual_volatility',
+})
+TRADING_DAYS_PER_YEAR = 252
+
+
+def _nan() -> float:
+    return float('nan')
+
+
+def _daily_ret(nav: list[float]) -> np.ndarray:
+    """nav[t]/nav[t-1] - 1; 第 1 个 = 0。"""
+    arr = np.asarray(nav, dtype=float)
+    if len(arr) < 2:
+        return np.zeros_like(arr)
+    ret = arr[1:] / arr[:-1] - 1.0
+    return np.concatenate([[0.0], ret])
+
+
+def _date_to_d(date_str: str) -> _date:
+    """'YYYYMMDD' → date."""
+    return _date(int(date_str[:4]), int(date_str[4:6]), int(date_str[6:8]))
+
+
+# ---- 收益 / 风险 (M1: 6 条) ----
+
+def total_return(nav: list[float]) -> float:
+    if len(nav) < 2:
+        return 0.0
+    return nav[-1] / nav[0] - 1.0
+
+
+def annual_return(nav: list[float]) -> float:
+    if len(nav) < 2:
+        return 0.0
+    days = len(nav) - 1
+    if days <= 0:
+        return 0.0
+    return (1.0 + total_return(nav)) ** (TRADING_DAYS_PER_YEAR / days) - 1.0
+
+
+def volatility(nav: list[float]) -> float:
+    """年化波动率 = std(daily_ret) * sqrt(252)。"""
+    ret = _daily_ret(nav)
+    if len(ret) < 2:
+        return 0.0
+    return float(np.nanstd(ret, ddof=1) * math.sqrt(TRADING_DAYS_PER_YEAR))
+
+
+def sharpe(nav: list[float], rf: float = 0.0) -> float:
+    """年化夏普 = mean(daily_ret) / std(daily_ret) * sqrt(252); rf 默认 0。"""
+    ret = _daily_ret(nav)
+    if len(ret) < 2:
+        return 0.0
+    excess = ret - rf / TRADING_DAYS_PER_YEAR
+    sd = np.nanstd(excess, ddof=1)
+    if sd == 0 or np.isnan(sd):
+        return 0.0
+    return float(np.nanmean(excess) / sd * math.sqrt(TRADING_DAYS_PER_YEAR))
+
+
+def max_drawdown(nav: list[float]) -> float:
+    """最大回撤 (正数, 0.05 = 5%)。"""
+    if not nav:
+        return 0.0
+    arr = np.asarray(nav, dtype=float)
+    peak = np.maximum.accumulate(arr)
+    dd = 1.0 - arr / peak
+    return float(np.nanmax(dd))
+
+
+# ---- 交易统计 (M1: 3 条) ----
+
+def _pair_trades(trades: list[dict]) -> list[tuple[dict, dict, float]]:
+    """FIFO 配对 buy/sell → (buy, sell, pnl)。"""
+    holdings: dict[str, list[dict]] = defaultdict(list)
+    pairs: list[tuple[dict, dict, float]] = []
+    for t in trades:
+        sym = t['symbol']
+        if t['side'] == 'buy':
+            holdings[sym].append({'orig': t, 'qty_left': t['qty']})
+        elif t['side'] == 'sell':
+            t_left = t['qty']
+            while holdings[sym] and t_left > 0:
+                buy = holdings[sym][0]
+                matched_qty = min(buy['qty_left'], t_left)
+                pnl = (t['price'] - buy['orig']['price']) * matched_qty
+                sell_view = {**t, 'qty': matched_qty}
+                pairs.append((buy['orig'], sell_view, pnl))
+                buy['qty_left'] -= matched_qty
+                t_left -= matched_qty
+                if buy['qty_left'] == 0:
+                    holdings[sym].pop(0)
+    return pairs
+
+
+def win_rate(trades: list[dict]) -> float:
+    """win_rate 0~1 (decimal, 与 v1 strategy_cli metrics 算法对齐)."""
+    pairs = _pair_trades(trades)
+    if not pairs:
+        return _nan()
+    wins = sum(1 for _, _, pnl in pairs if pnl > 0)
+    return wins / len(pairs)
+
+
+def profit_loss_ratio(trades: list[dict]) -> float:
+    """profit_loss_ratio = mean(wins) / abs(mean(losses)). 无 wins 或 losses → NaN."""
+    pairs = _pair_trades(trades)
+    if not pairs:
+        return _nan()
+    wins = [pnl for _, _, pnl in pairs if pnl > 0]
+    losses = [pnl for _, _, pnl in pairs if pnl < 0]
+    if not wins or not losses:
+        return _nan()
+    return float(np.mean(wins) / abs(np.mean(losses)))
+
+
+def avg_holding_period(trades: list[dict]) -> float:
+    """平均持仓自然日 (calendar days)."""
+    pairs = _pair_trades(trades)
+    if not pairs:
+        return _nan()
+    days = [(_date_to_d(s['date']) - _date_to_d(b['date'])).days for b, s, _ in pairs]
+    return float(np.mean(days))
+
+
+# ---- M2 新增 4 条 ----
+
+def sortino(nav: list[float], rf: float = 0.0) -> float:
+    """Sortino = mean(excess) / downside_std * sqrt(252)."""
+    ret = _daily_ret(nav)
+    if len(ret) < 2:
+        return 0.0
+    excess = ret - rf / TRADING_DAYS_PER_YEAR
+    downside = excess[excess < 0]
+    if len(downside) == 0:
+        return 0.0
+    sd = np.sqrt(np.mean(downside ** 2))
+    if sd == 0:
+        return 0.0
+    return float(np.nanmean(excess) / sd * math.sqrt(TRADING_DAYS_PER_YEAR))
+
+
+def calmar(nav: list[float]) -> float:
+    """Calmar = annual_return / max_drawdown. 无回撤时 NaN."""
+    mdd = max_drawdown(nav)
+    if mdd == 0:
+        return _nan()
+    return annual_return(nav) / mdd
+
+
+def var_95(nav: list[float]) -> float:
+    """VaR (95%) = -5% 分位日收益 (正数表示风险大小, 0.02 = 2%)."""
+    ret = _daily_ret(nav)
+    if len(ret) < 2:
+        return _nan()
+    return float(-np.percentile(ret, 5))
+
+
+def profit_factor(trades: list[dict]) -> float:
+    """profit_factor = sum(wins) / sum(|losses|). 无亏损或无成交时 NaN."""
+    pairs = _pair_trades(trades)
+    if not pairs:
+        return _nan()
+    wins = sum(pnl for _, _, pnl in pairs if pnl > 0)
+    losses = sum(abs(pnl) for _, _, pnl in pairs if pnl < 0)
+    if losses == 0 or wins == 0:
+        return _nan()
+    return wins / losses
+
+
+# ---- 入口 ----
+
+def compute_all(nav_curve: list[dict], trades: list[dict]) -> dict[str, float]:
+    """算全部 15 条 metrics.
+
+    输入: nav_curve = [{date, nav}], trades = [{symbol, side, price, qty, date}, ...].
+    输出: {metric_key: float}, NaN 表示不适用.
+
+    benchmark_total_return / excess_return 永远 NaN (akquant 单策略无自动基准).
+    """
+    nav = [p['nav'] for p in nav_curve]
+    return {
+        # M1 (10)
+        'total_return':       total_return(nav),
+        'annual_return':      annual_return(nav),
+        'sharpe':             sharpe(nav),
+        'max_drawdown':       max_drawdown(nav),
+        'volatility':         volatility(nav),
+        'win_rate':           win_rate(trades),
+        'profit_loss_ratio':  profit_loss_ratio(trades),
+        'avg_holding_period': avg_holding_period(trades),
+        'benchmark_total_return': _nan(),
+        'excess_return':          _nan(),
+        # M2 (4)
+        'sortino':            sortino(nav),
+        'calmar':             calmar(nav),
+        'var_95':             var_95(nav),
+        'profit_factor':      profit_factor(trades),
+        # alias
+        'annual_volatility':  volatility(nav),
+    }
+
+
+# ---- 月度聚合 ----
+
+def monthly_bars(nav_curve: list[dict]) -> list[dict]:
+    """按月汇总: monthly_bars[k] = {month: 'YYYY-MM', return, drawdown_bar}."""
+    if not nav_curve:
+        return []
+    by_month: dict[str, dict] = {}
+    for p in nav_curve:
+        m = p['date'][:6]
+        if m not in by_month:
+            by_month[m] = {'first': p, 'last': p}
+        else:
+            by_month[m]['last'] = p
+    bars = []
+    for m in sorted(by_month.keys()):
+        first, last = by_month[m]['first'], by_month[m]['last']
+        ret = last['nav'] / first['nav'] - 1 if first['nav'] else 0.0
+        bars.append({
+            'month': f'{m[:4]}-{m[4:6]}',
+            'return': float(ret),
+            'drawdown_bar': float(max(0.0, -ret)),
+        })
+    return bars
+
+
+def monthly_metrics(nav_curve: list[dict]) -> dict[str, dict[str, float]]:
+    """UI 月度热力图: {YYYY: {MM: ret}}."""
+    bars = monthly_bars(nav_curve)
+    out: dict[str, dict[str, float]] = {}
+    for b in bars:
+        y, mo = b['month'].split('-')
+        out.setdefault(y, {})[mo] = b['return']
+    return out
+
+
+def _selfcheck() -> None:
+    """mock 测试: 已知 nav + trades 序列 → 验 15 keys + 边界.
+
+    与原仓根 `hamuna_quant_cli/references/_metrics_15.py` 同测试集, 输出应
+    完全一致 (B 重写 parity 要求).
+
+    🧪 单元测试用已知 nav + trades 序列. 显式门控: 仅当 `HAMUNA_SELFTEST=1` 时执行,
+    防止 Agent 误调以为是 prod 数据校验. 调用方式:
+        HAMUNA_SELFTEST=1 python -c "from ..._metrics_15 import _selfcheck; _selfcheck()"
+    """
+    import os
+    if os.environ.get("HAMUNA_SELFTEST") != "1":
+        raise RuntimeError(
+            "_selfcheck() 用 mock nav+trades 验 metrics 公式, 不用于 prod 数据校验. "
+            "设置 HAMUNA_SELFTEST=1 显式启用."
+        )
+    # 1) nav_curve 长度 < 2 → total_return = 0
+    m = compute_all([], [])
+    assert set(m.keys()) == HAMUNA_METRICS_15, f'metrics key 缺/多: {set(m.keys()) ^ HAMUNA_METRICS_15}'
+    assert m['total_return'] == 0.0
+    assert m['benchmark_total_return'] != m['benchmark_total_return']  # NaN
+    print(f'OK: 15 metrics keys 对齐, 空输入 → total=0 + bench=NaN')
+
+    # 2) 单调递增 nav → total_return > 0, sharpe > 0
+    nav_curve = [{'date': f'2024{i:02d}02', 'nav': 100 + i} for i in range(1, 7)]
+    m = compute_all(nav_curve, [])
+    assert m['total_return'] > 0
+    assert m['sharpe'] > 0
+    assert m['max_drawdown'] == 0  # 单调无回撤
+    print(f"OK: 单调递增 nav → total={m['total_return']:.4f}, sharpe={m['sharpe']:.2f}, mdd=0")
+
+    # 3) trades: 1 win + 1 loss → win_rate=0.5, pl=1.0, pf=1.0
+    trades = [
+        {'date': '20240101', 'symbol': 'X', 'side': 'buy', 'price': 10.0, 'qty': 100},
+        {'date': '20240110', 'symbol': 'X', 'side': 'sell', 'price': 11.0, 'qty': 100},
+        {'date': '20240111', 'symbol': 'X', 'side': 'buy', 'price': 12.0, 'qty': 100},
+        {'date': '20240120', 'symbol': 'X', 'side': 'sell', 'price': 11.0, 'qty': 100},
+    ]
+    m = compute_all(nav_curve, trades)
+    assert abs(m['win_rate'] - 0.5) < 1e-6, f'win_rate 应 0.5, 实际 {m["win_rate"]}'
+    assert abs(m['profit_loss_ratio'] - 1.0) < 1e-6, f'pl 应 1.0, 实际 {m["profit_loss_ratio"]}'
+    assert abs(m['profit_factor'] - 1.0) < 1e-6, f'pf 应 1.0, 实际 {m["profit_factor"]}'
+    print(f"OK: 1 win + 1 loss → win_rate={m['win_rate']:.2f}, pl={m['profit_loss_ratio']:.2f}, "
+          f"pf={m['profit_factor']:.2f}")
+
+    # 4) 全胜 → win_rate=1, pl=NaN, pf=NaN (修复前 bug: pf=1e11)
+    trades_win = trades[:2]
+    m = compute_all(nav_curve, trades_win)
+    assert m['win_rate'] == 1.0
+    assert m['profit_loss_ratio'] != m['profit_loss_ratio']  # NaN
+    assert m['profit_factor'] != m['profit_factor']  # NaN
+    print(f"OK: 全胜边界 win_rate=1, pl=NaN, pf=NaN")
+
+    # 5) 全败 → win_rate=0, pl=NaN, pf=NaN
+    trades_all_loss = [
+        {'date': '20240101', 'symbol': 'X', 'side': 'buy', 'price': 10.0, 'qty': 100},
+        {'date': '20240110', 'symbol': 'X', 'side': 'sell', 'price': 9.0, 'qty': 100},
+        {'date': '20240111', 'symbol': 'X', 'side': 'buy', 'price': 12.0, 'qty': 100},
+        {'date': '20240120', 'symbol': 'X', 'side': 'sell', 'price': 11.0, 'qty': 100},
+    ]
+    m = compute_all(nav_curve, trades_all_loss)
+    assert m['win_rate'] == 0.0
+    assert m['profit_loss_ratio'] != m['profit_loss_ratio']  # NaN
+    assert m['profit_factor'] != m['profit_factor']  # NaN
+    print(f"OK: 全败边界 win_rate=0, pl=NaN, pf=NaN")
+
+
+if __name__ == '__main__':
+    _selfcheck()