powerquant-cli 0.2.6__py3-none-any.whl

quant_cli/examples/strategies/trend_drawdown_guard.py

@@ -0,0 +1,22 @@
+"""多标的趋势策略：正动量且近期回撤受控时持有，失效则退出。"""
+
+from decimal import Decimal
+
+
+async def on_bar(event, context):
+    instrument_id = event.payload.instrument_id
+    momentum = context.factor_value("momentum_20d", instrument_id)
+    drawdown = context.factor_value("max_drawdown_20d", instrument_id)
+    volume_ratio = context.factor_value("volume_ratio_5d", instrument_id)
+    if None in (momentum, drawdown, volume_ratio):
+        return []
+    position = await context.portfolio.get_position(instrument_id)
+    held = position.quantity if position else 0
+    if context.get_open_orders(instrument_id):
+        return []
+    allowed = momentum > 0 and drawdown >= Decimal("-0.12") and volume_ratio >= Decimal("0.7")
+    if allowed and not held:
+        context.order_target_percent(instrument_id, Decimal("0.2"))
+    elif not allowed and held:
+        context.order_target(instrument_id, 0)
+    return []

quant_cli/examples/strategies/weekly_risk_adjusted_rotation.py

@@ -0,0 +1,61 @@
+"""每周三因子轮动：与研究入口共用因子排名和缺值规则。"""
+
+from decimal import Decimal
+
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+from quant_core.app.factor.schema.selection_types import (
+    FactorFilter,
+    FactorTransform,
+    FactorWeight,
+    NormalizationMethod,
+    SelectionDefinition,
+)
+
+
+def _identity(name):
+    return FactorIdentity(name=name, source="local-python", definition_version="3")
+
+
+SELECTION = SelectionDefinition(
+    factors=(
+        FactorWeight(
+            _identity("momentum_20d"),
+            Decimal(1),
+            transform=FactorTransform(normalization=NormalizationMethod.RANK),
+        ),
+        FactorWeight(
+            FactorIdentity(
+                name="risk_adjusted_momentum_20d", source="local-python", definition_version="1"
+            ),
+            Decimal(1),
+            transform=FactorTransform(normalization=NormalizationMethod.RANK),
+        ),
+    ),
+    filters=(
+        FactorFilter(_identity("momentum_20d"), minimum=Decimal(0)),
+        FactorFilter(_identity("volume_ratio_5d"), minimum=Decimal("0.6")),
+    ),
+    top_n=2,
+)
+
+
+async def on_bar(event, context):
+    week = context.event_time.isocalendar()[:2]
+    if context.state.get("rebalance_week") == week:
+        return []
+    if any(
+        (bar := context.current(instrument_id)) is None or bar.timestamp != context.event_time
+        for instrument_id in context.universe
+    ):
+        return []
+
+    selected = {row.instrument_id for row in context.select_factors(SELECTION).selected}
+    weight = Decimal("0.9") / len(selected) if selected else Decimal("0")
+    context.rebalance(
+        {
+            instrument_id: weight if instrument_id in selected else Decimal("0")
+            for instrument_id in context.universe
+        }
+    )
+    context.state["rebalance_week"] = week
+    return []

quant_cli/examples/unified_snapshot_validation.py

@@ -0,0 +1,260 @@
+"""同一快照的真实 CLI 验收；日期固定为 2026-09 样本，不评价因子投资价值。"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from datetime import date, datetime, time
+from decimal import Decimal
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from quant_core.app.backtest.schema import BacktestResult
+
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+
+CN = ZoneInfo("Asia/Shanghai")
+SOURCE = (
+    "from quant_core.app.factor.computation.factor_expression import MA, Factor\n"
+    "factors = {'reversal5': -MA(Factor('close') / Factor('open') - 1, 5)}"
+)
+STRATEGY = """def handle_bar(context, bars):
+    if context.event_time.date().isoformat() == "2026-09-28":
+        rows = context.factors.get("reversal5", {})
+        scores = [(key, context.factor_value("reversal5", key)) for key in context.universe]
+        assert all(value is not None for key, value in scores), "missing visible factor"
+        assert all(row.available_at <= context.event_time for row in rows.values())
+        assert all(row.as_of.date().isoformat() == "2026-09-24" for row in rows.values())
+        selected = [key for key, value in sorted(scores, key=lambda row: (-row[1], row[0]))[:3]]
+        context.state["selected"] = selected
+        for key in selected:
+            context.order_shares(key, 200)
+    elif context.event_time.date().isoformat() == "2026-09-30":
+        for key in context.state.get("selected", []):
+            context.order_target(key, 0)
+"""
+BOOTSTRAP = """
+import asyncio, sys
+from importlib.abc import MetaPathFinder
+from unittest.mock import patch
+class Guard(MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname.startswith('quant_backend'):
+            raise AssertionError('Remote infrastructure import: ' + fullname)
+sys.meta_path.insert(0, Guard())
+from quant_cli.app.quant_cli import main
+with asyncio.Runner() as runner:
+    runner.get_loop()
+    with (
+        patch('socket.socket', side_effect=AssertionError('Offline network access')),
+        patch('asyncio.run', runner.run),
+    ):
+        main()
+"""
+
+
+def command(*args: str, expected: int = 0) -> dict | list:
+    result = subprocess.run(
+        [sys.executable, "-c", BOOTSTRAP, *args],
+        cwd=Path(__file__).parents[1],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        env={**os.environ, "PYTHONIOENCODING": "utf-8"},
+        timeout=180,
+    )
+    if result.returncode != expected:
+        raise AssertionError(f"CLI failed {args}: {result.stdout}\n{result.stderr}")
+    return json.loads(result.stdout)
+
+
+def validate(manifest: Path, output: Path) -> dict:
+    output.mkdir(parents=True, exist_ok=True)
+    database = str(output / "research.duckdb")
+    market, _ = load_dataset(manifest, 1000000)
+    ids = sorted(market.facts)
+
+    def config(name: str, payload: dict) -> str:
+        path = output / f"{name}.json"
+        path.write_text(
+            json.dumps(payload, default=str, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+        return str(path)
+
+    audit = command(
+        "data",
+        "audit",
+        "--manifest",
+        str(manifest),
+        "--config",
+        config(
+            "audit-request",
+            {
+                "instrument_ids": ids,
+                "start": "2026-09-02",
+                "end": "2026-09-30",
+            },
+        ),
+    )
+    assert audit["ready"]
+    config("audit-report", audit)
+    factor = command(
+        "factor",
+        "compute",
+        "--database",
+        database,
+        "--config",
+        config(
+            "factor-request",
+            {
+                "source": SOURCE,
+                "manifest_path": str(manifest),
+                "instrument_ids": ids,
+                "start": "2026-09-08",
+                "end": "2026-09-29",
+            },
+        ),
+    )
+    cells = command(
+        "factor", "values", "--run", factor["uuid"], "--limit", "10000", "--database", database
+    )
+    assert len(cells) == factor["result"]["cells"]
+    error = Decimal(0)
+    labels, selection = [], []
+    for instrument in ids:
+        facts = market.facts[instrument]
+        days = sorted(row.trade_date for row in facts.calendar if row.is_open)
+        bars = {bar.timestamp.astimezone(CN).date(): bar for bar in market.bars[(instrument, "1d")]}
+        for cell in (row for row in cells if row["instrument_id"] == instrument):
+            ts = datetime.fromisoformat(cell["as_of"])
+            day = ts.astimezone(CN).date()
+            index = days.index(day)
+            window = [bars.get(d) for d in days[max(0, index - 4) : index + 1]]
+            expected = None
+            if len(window) == 5 and all(
+                bar and not bar.suspended and bar.open > 0 for bar in window
+            ):
+                expected = -sum((bar.close / bar.open - 1 for bar in window), Decimal(0)) / 5
+            actual = None if cell["value"] is None else Decimal(cell["value"])
+            assert (expected is None) == (actual is None)
+            if expected is not None:
+                error = max(error, abs(expected - actual))
+                assert abs(expected - actual) < Decimal("1e-12")
+            if day == date(2026, 9, 24) and expected is not None:
+                selection.append((instrument, expected))
+            if index + 2 < len(days) and days[index + 2] <= date(2026, 9, 24):
+                buy, sell = bars.get(days[index + 1]), bars.get(days[index + 2])
+                if not buy or not sell or buy.suspended or sell.suspended:
+                    continue
+                labels.append(
+                    {
+                        "decision_time": ts.isoformat(),
+                        "instrument_id": instrument,
+                        "end_time": datetime.combine(days[index + 2], time(15), CN).isoformat(),
+                        "value": str(sell.close / buy.close - 1),
+                        "price_basis": "raw-next-close-to-following-close",
+                        "data_revision": market.revision,
+                    }
+                )
+    research = command(
+        "research",
+        "evaluate",
+        "--database",
+        database,
+        "--config",
+        config(
+            "research-request",
+            {
+                "factor_run_uuid": factor["uuid"],
+                "factor_name": "reversal5",
+                "labels": labels,
+                "quantiles": 2,
+            },
+        ),
+    )
+    backtest_request = {
+        "source": STRATEGY,
+        "manifest_path": str(manifest),
+        "factor_run_uuid": factor["uuid"],
+        "config": {
+            "strategy_id": "unified_snapshot",
+            "instrument_ids": ids,
+            "frequency": "1d",
+            "start": "2026-09-28T09:30:00+08:00",
+            "end": "2026-09-30T15:00:00+08:00",
+            "initial_cash": "1000000",
+            "strategy_adjustment_type": "none",
+        },
+    }
+    backtest = command(
+        "backtest",
+        "run",
+        "--database",
+        database,
+        "--config",
+        config("backtest-request", backtest_request),
+    )
+    runs = {"factor": factor, "research": research, "backtest": backtest}
+    for kind, record in runs.items():
+        assert record["provenance"]["market_revision"] == market.revision
+        assert record["provenance"]["manifest_digest"] == factor["provenance"]["manifest_digest"]
+        assert command(kind, "get", "--run", record["uuid"], "--database", database) == record
+    result = BacktestResult.model_validate(backtest["result"])
+    top = [key for key, score in sorted(selection, key=lambda row: (-row[1], row[0]))[:3]]
+    assert len(result.fills) == 6
+    assert sorted(
+        fill.instrument_id for fill in result.fills if fill.side.value == "buy"
+    ) == sorted(top)
+    cash = Decimal(1000000) + sum(
+        (
+            (1 if fill.side.value == "sell" else -1) * fill.price * fill.quantity - fill.fees.total
+            for fill in result.fills
+        ),
+        Decimal(0),
+    )
+    assert result.final_portfolio_snapshot.cash.total_cash == cash
+    # 新进程再次回放：业务结果稳定，运行 UUID 可以变化。
+    repeat = command(
+        "backtest", "run", "--database", database, "--config", str(output / "backtest-request.json")
+    )
+    repeated = BacktestResult.model_validate(repeat["result"])
+    assert repeated.final_portfolio_snapshot.cash.total_cash == cash
+    assert [(f.instrument_id, f.side, f.quantity, f.price, f.fees.total) for f in result.fills] == [
+        (f.instrument_id, f.side, f.quantity, f.price, f.fees.total) for f in repeated.fills
+    ]
+    report = {
+        "status": "passed",
+        "manifest": str(manifest),
+        "market_revision": market.revision,
+        "manifest_digest": factor["provenance"]["manifest_digest"],
+        "runs": {k: v["uuid"] for k, v in runs.items()},
+        "repeat_backtest": repeat["uuid"],
+        "instruments": ids,
+        "selected": top,
+        "factor_cells": len(cells),
+        "maximum_error": str(error),
+        "fills": len(result.fills),
+        "final_cash": str(cash),
+        "limitations": [
+            "固定五股工程样本，非全市场验收",
+            "原始价格标签仅用于流程检查，未评价投资有效性",
+            "当前修订快照不代表完整历史知识时间 PIT",
+        ],
+    }
+    config("validation-report", report)
+    (output / "report.md").write_text(
+        "# 同一快照端到端验证\n\n```json\n"
+        + json.dumps(report, ensure_ascii=False, indent=2)
+        + "\n```\n",
+        encoding="utf-8",
+    )
+    return report
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--manifest", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+    print(json.dumps(validate(args.manifest.resolve(), args.output.resolve()), ensure_ascii=False))

quant_core/app/SPEC.md

@@ -0,0 +1,18 @@
+# 计算核心边界
+
+本目录承载数据契约、因子、研究、策略、交易运行、订单、组合与回测计算。通用工程规则见 [SPEC.md](../../../../../SPEC.md)。
+
+```text
+调用方提供输入和协议实现
+          |
+          v
+schema / interface -> service / computation -> 结构化结果
+```
+
+- 核心不访问 HTTP、PostgreSQL、DuckDB、Redis，不读取应用配置，不导入应用或 SDK。
+- Service 依赖消费方拥有的最小 Protocol；具体供数及持久化在应用中组装。
+- CLI 负责参数、批量输入准备和本地归档；后端负责身份认证及发布定义管理。
+- 纯计算使用函数；有运行状态或明确生命周期的对象使用类，不为目录完整创建空层。
+- Strategy 保持环境无关。Backtest 单向依赖 Trading Runtime；Runtime 不依赖 Backtest。
+- Order Execution 产生 Fill，Portfolio 应用 Fill；订单被接受不会改变资金持仓。
+- 不同运行共享核算规则，不共享可变账户状态。

quant_core/app/backtest/SPEC.md

@@ -0,0 +1,65 @@
+# Backtest SPEC
+
+## 1. Domain Purpose
+
+`backtest` 负责定义、组装和运行一次历史策略回测，并产出可复现的结果、指标和决策轨迹。它使用 Trading Runtime 的通用事件循环，不拥有另一套 Runtime。
+
+## 2. Responsibilities
+
+- 管理 BacktestRun、BacktestConfig 和运行生命周期。
+- 组装 HistoricalClock、Historical Market Replay、Simulated Order Execution 与 Simulated Portfolio。
+- 回测启动前验证所需 Market 数据。
+- 调用 Trading Runtime 执行历史事件循环。
+- 生成 BacktestResult、交易记录、资金曲线、绩效指标和 trace。
+
+## 3. Non-Responsibilities
+
+- 不定义或复制 Strategy Logic。
+- 不实现通用时间片事件循环。
+- 不拥有 Canonical Order、Fill 或 Portfolio 规则。
+- 不修改 Paper 或 Live Portfolio。
+- 不生成研究结论、机会状态或通知。
+
+## 4. Main Concepts
+
+```text
+BacktestRun
+├── BacktestConfig
+├── HistoricalClock
+├── HistoricalReplay
+├── Simulated Execution Configuration
+├── Simulated Portfolio Initialization
+└── BacktestResult
+    ├── Trades
+    ├── Equity Curve
+    ├── Metrics
+    └── Decision Trace
+```
+
+## 5. Dependency Direction
+
+```text
+Backtest
+├──> Trading Runtime
+├──> Market
+├──> Strategy
+├──> Order Execution
+└──> Portfolio
+
+Trading Runtime -X-> Backtest
+```
+
+Backtest 负责选择并组装历史环境实现；Trading Runtime 只运行被注入的契约，不得通过 `if mode == BACKTEST` 依赖本域。
+
+## 6. Important Business Rules
+
+- PowerQuant 自有事件驱动回测是唯一权威回测路径，第三方项目只作为设计参考。
+- 数据缺失或无效时拒绝启动，运行中禁止隐式同步或修复 Market 数据。
+- Replay 使用精确相等 `event_time` 的 `MarketTimeSlice`。
+- 新订单不得使用策略作出决策之前的市场事实成交。
+- 相同输入、配置和策略版本必须产生相同业务结果。
+- 回测状态与 Paper、Live 状态严格隔离。
+
+## 7. Application Entry
+
+`execute_backtest` 执行共享回测用例，接收已组装的行情组件与计算依赖。CLI 负责本地快照准备和 DuckDB 归档；核心不创建数据库会话，不访问远端服务。

quant_core/app/backtest/__init__.py

@@ -0,0 +1 @@
+"""Backtest Domain - 历史回测运行与结果。"""

quant_core/app/backtest/backtest_input_schema.py

@@ -0,0 +1,20 @@
+"""历史运行的显式输入组件，无文件加载副作用。"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from quant_core.app.data.service.prepared_data_verification_service import PreparedDataVerification
+from quant_core.app.data.service.prepared_market_service import PreparedMarketData
+from quant_core.app.trading_runtime.replay.exchange_state_resolver import ExchangeStateResolver
+from quant_core.app.trading_runtime.replay.market_runtime_service import ReplayMarketEventSource
+from quant_core.app.trading_runtime.replay.market_state_resolver import MarketStateResolver
+
+
+@dataclass(frozen=True)
+class BacktestMarketComponents:
+    query: PreparedMarketData
+    verification: PreparedDataVerification
+    slice_source: ReplayMarketEventSource
+    market_state_resolver: MarketStateResolver
+    exchange_state_resolver: ExchangeStateResolver
+    manifest_path: Path