powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/strategy/interface/strategy_order_reader.py

@@ -0,0 +1,14 @@
+"""Order view consumed by strategy context."""
+
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.order_execution.domain.order_value import OrderSnapshot
+
+
+@runtime_checkable
+class IStrategyOrderReader(Protocol):
+    def get_order(self, order_id: str) -> OrderSnapshot | None: ...
+
+    def open_order_snapshots(
+        self, instrument_id: str | None = None
+    ) -> tuple[OrderSnapshot, ...]: ...

quant_core/app/strategy/schema/portfolio_schema.py

@@ -0,0 +1,28 @@
+"""
+Portfolio Schema - Strategy 可读的持仓/资金视图（只读快照）
+
+边界（硬规则）：Strategy 可以读取持仓，但不能拥有或修改持仓。
+cash/position 的真实状态归 Portfolio / Backtest；资产变化只发生在
+Signal → Backtest/Execution → Order → Fill → Portfolio Update 链路上。
+"""
+
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PositionView(BaseModel):
+    """单个标的的持仓只读视图（不暴露 cost basis 之外的可变语义）"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    instrument_id: str = Field(..., description="Canonical 标的 ID")
+    quantity: int = Field(..., description="持仓股数（0 = 未持仓）")
+
+
+class CashView(BaseModel):
+    """资金只读视图"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    cash: Decimal = Field(..., ge=0, description="可用资金（Decimal，与资金类字段精度规范一致）")

quant_core/app/strategy/schema/portfolio_target.py

@@ -0,0 +1,70 @@
+"""选股分数到目标组合的约束与可解释输出。"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+
+from quant_core.app.factor.schema.selection_types import SelectionResult
+
+
+@dataclass(frozen=True)
+class PortfolioConstraints:
+    max_positions: int = 10
+    max_weight: Decimal = Decimal("1")
+    cash_buffer: Decimal = Decimal("0.02")
+    industry_caps: tuple[tuple[str, Decimal], ...] = ()
+    max_turnover: Decimal | None = None
+    retention_rank: int | None = None
+    max_replacements: int | None = None
+    min_holding_sessions: int = 0
+
+    def __post_init__(self) -> None:
+        if self.retention_rank is not None and self.retention_rank < self.max_positions:
+            raise ValueError("保留排名阈值不得小于目标持仓数")
+        if self.max_replacements is not None and self.max_replacements < 0:
+            raise ValueError("最大替换数量不得为负")
+        if self.min_holding_sessions < 0:
+            raise ValueError("最低持有交易日不得为负")
+        if (
+            self.max_positions < 1
+            or not self.max_weight.is_finite()
+            or not Decimal(0) < self.max_weight <= 1
+        ):
+            raise ValueError("持仓数和单股权重上限非法")
+        if not self.cash_buffer.is_finite() or not Decimal(0) <= self.cash_buffer < 1:
+            raise ValueError("现金缓冲必须在 [0,1)")
+        if len(dict(self.industry_caps)) != len(self.industry_caps):
+            raise ValueError("行业权重上限重复")
+        if any(not cap.is_finite() or not Decimal(0) <= cap <= 1 for _, cap in self.industry_caps):
+            raise ValueError("行业权重上限非法")
+        if self.max_turnover is not None and (
+            not self.max_turnover.is_finite() or not Decimal(0) <= self.max_turnover <= 1
+        ):
+            raise ValueError("换手上限必须在 [0,1]")
+
+
+@dataclass(frozen=True)
+class TargetPortfolio:
+    weights: tuple[tuple[str, Decimal], ...]
+    cash_weight: Decimal
+    reasons: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if len(dict(self.weights)) != len(self.weights):
+            raise ValueError("组合目标证券重复")
+        if any(not weight.is_finite() or weight < 0 for _, weight in self.weights):
+            raise ValueError("组合权重非法")
+        if (
+            not self.cash_weight.is_finite()
+            or self.cash_weight < 0
+            or sum((weight for _, weight in self.weights), Decimal(0)) + self.cash_weight != 1
+        ):
+            raise ValueError("持仓及现金权重必须合计为 1")
+
+
+@dataclass(frozen=True)
+class PortfolioDecision:
+    """评分贡献与目标组合的同次决策证据，随回测结果持久化，不驱动交易状态。"""
+
+    selection: SelectionResult
+    target: TargetPortfolio
+    constraints: PortfolioConstraints

quant_core/app/strategy/schema/python_strategy_schema.py

@@ -0,0 +1,94 @@
+"""Immutable Python strategy publication and run input."""
+
+import ast
+import hashlib
+import json
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+
+
+class PythonStrategySpec(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    strategy_id: str = Field(pattern=r"^[a-z][a-z0-9_]*$", max_length=64)
+    version: str = Field(min_length=1, max_length=32)
+    name: str = Field(min_length=1, max_length=128)
+    description: str = ""
+    python_source: str = Field(min_length=1, max_length=65536)
+    factor_refs: tuple[FactorIdentity, ...] = ()
+    factor_aliases: dict[str, FactorIdentity] = Field(default_factory=dict)
+    parameters: dict[str, Any] = Field(default_factory=dict)
+    universe: tuple[str, ...] = ()
+    submitted_by: str | None = None
+
+    @property
+    def source_digest(self) -> str:
+        return hashlib.sha256(self.python_source.encode("utf-8")).hexdigest()
+
+    @property
+    def content_digest(self) -> str:
+        payload = self.model_dump(mode="json", exclude={"submitted_by"})
+        if not self.factor_aliases:
+            payload.pop("factor_aliases")  # 保留既有不可变版本摘要
+        return hashlib.sha256(
+            json.dumps(payload, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode(
+                "utf-8"
+            )
+        ).hexdigest()
+
+    def resolved_factors(self) -> dict[str, FactorIdentity]:
+        """将编写别名绑定完整身份；同名多版本必须显式绑定。"""
+        refs = {item.logical_key: item for item in self.factor_refs}
+        if len(refs) != len(self.factor_refs):
+            raise ValueError("策略因子依赖重复")
+        bindings = dict(self.factor_aliases)
+        for alias, identity in bindings.items():
+            if not alias.isidentifier() or identity.logical_key not in refs:
+                raise ValueError("因子别名必须合法且引用已声明的完整身份")
+        bound = {item.logical_key for item in bindings.values()}
+        for identity in self.factor_refs:
+            if identity.logical_key in bound:
+                continue
+            if identity.name in bindings:
+                raise ValueError("同名因子依赖存在歧义，请为每个身份声明不同别名")
+            bindings[identity.name] = identity
+        return bindings
+
+    def validate_source(self) -> None:
+        self.resolved_factors()
+        module = ast.parse(self.python_source)
+        callbacks = {
+            node.name: node
+            for node in module.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        }
+        if not callbacks.keys() & {"handle_bar", "on_bar", "on_session", "on_slice"}:
+            raise ValueError("策略源码至少定义 handle_bar、on_bar、on_session 或 on_slice 回调")
+        for name, expected in {
+            "init": 1,
+            "handle_bar": 2,
+            "on_bar": 2,
+            "on_slice": 2,
+            "on_session": 2,
+            "before_trading": 1,
+            "after_trading": 1,
+        }.items():
+            node = callbacks.get(name)
+            if node is None:
+                continue
+            positional = len(node.args.posonlyargs) + len(node.args.args)
+            if (
+                positional != expected
+                or node.args.vararg is not None
+                or node.args.kwarg is not None
+                or node.args.kwonlyargs
+            ):
+                raise ValueError(f"{name} 回调必须声明 {expected} 个位置参数")
+        if len(self.python_source.encode("utf-8")) > 65536:
+            raise ValueError("策略源码超过 64 KiB")
+        identities = [item.logical_key for item in self.factor_refs]
+        if len(set(identities)) != len(identities):
+            raise ValueError("策略因子依赖重复")

quant_core/app/strategy/schema/screener_schema.py

@@ -0,0 +1,51 @@
+"""
+Screener Schema - 候选标的筛选/排名契约
+
+Universe → Factor Values → Filter → Rank → Top N → ScreenerResult。
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.factor.schema.factor_contract import FactorValue
+from quant_core.app.strategy.schema.strategy_schema import ScreenerSpec
+
+
+class ScreenerCandidate(BaseModel):
+    """筛选后的单个候选标的"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    instrument_id: str = Field(..., description="Canonical 标的 ID")
+    score: Decimal = Field(..., description="排名得分（rank_by 的值）")
+    factor_values: dict[str, Decimal | None] = Field(
+        default_factory=dict, description="各因子值快照（血缘/可解释性）"
+    )
+
+
+class ScreenerRequest(BaseModel):
+    """筛选请求"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    universe: list[str] = Field(..., description="候选标的池（Canonical ID）")
+    event_time: datetime = Field(..., description="市场事件时间")
+    spec: ScreenerSpec = Field(
+        ..., description="筛选/排名规则（Canonical，来自 StrategyDefinition.screening_rules）"
+    )
+    factor_values: dict[str, list[FactorValue]] = Field(
+        default_factory=dict, description="factor_name → 各标的 Canonical FactorValue（R2-1）"
+    )
+
+
+class ScreenerResult(BaseModel):
+    """筛选结果"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    event_time: datetime = Field(..., description="市场事件时间")
+    candidates: list[ScreenerCandidate] = Field(default_factory=list, description="按得分降序")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="扩展元数据")

quant_core/app/strategy/schema/signal_schema.py

@@ -0,0 +1,33 @@
+"""
+Signal Schema - Strategy 的 Canonical Decision Result
+
+边界（硬规则）：Strategy 只产生 Signal，不产生 Broker Order。
+Strategy 回答「应该做什么」，Execution / Backtest 回答「怎么成交」。
+"""
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.strategy.constants import SignalSide, SignalType
+
+
+class Signal(BaseModel):
+    """策略信号——Strategy 某时点产生的结构化决策结果"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    signal_id: str = Field(default_factory=lambda: str(uuid4()), description="信号唯一标识")
+    strategy_id: str = Field(..., description="策略标识（StrategyDefinition.strategy_id）")
+    strategy_version: str = Field("1", description="策略版本")
+    instrument_id: str = Field(..., description="Canonical 标的 ID")
+    event_time: datetime = Field(..., description="市场事件时间（Strategy 只认这个）")
+    signal_type: SignalType = Field(..., description="信号类型")
+    side: SignalSide = Field(SignalSide.LONG, description="方向（A股 V1：LONG/NONE）")
+    score: Decimal | None = Field(None, description="信号强度评分")
+    reason: str = Field("", description="人类可读的决策原因（可审计）")
+    factor_refs: list[str] = Field(default_factory=list, description="引用的因子名（血缘）")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="扩展元数据")

quant_core/app/strategy/schema/strategy_publication_schema.py

@@ -0,0 +1,32 @@
+"""离线策略包固定定义及全部因子依赖，不包含计算结果。"""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from quant_core.app.factor.schema.factor_publication_schema import PublishedFactor
+from quant_core.app.strategy.schema.python_strategy_schema import PythonStrategySpec
+
+
+class PublishedStrategy(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    format_version: Literal[1] = 1
+    definition: PythonStrategySpec
+    content_digest: str
+    factors: tuple[PublishedFactor, ...] = ()
+
+    @model_validator(mode="after")
+    def verify(self) -> "PublishedStrategy":
+        self.definition.validate_source()
+        if (
+            self.definition.version == "latest"
+            or self.definition.content_digest != self.content_digest
+        ):
+            raise ValueError("策略版本未固定或摘要不匹配")
+        expected = {ref.logical_key for ref in self.definition.factor_refs}
+        actual = [factor.definition.identity.logical_key for factor in self.factors]
+        if len(actual) != len(set(actual)) or set(actual) != expected:
+            raise ValueError("策略包必须包含准确且完整的固定因子依赖")
+        if any(ref.definition_version == "latest" for ref in self.definition.factor_refs):
+            raise ValueError("策略因子依赖不能使用 latest")
+        return self

quant_core/app/strategy/schema/strategy_schema.py

@@ -0,0 +1,96 @@
+"""
+Strategy Schema - StrategyDefinition（Canonical 契约）
+
+StrategyDefinition 描述完整交易决策规则（Artifact），不是运行中的实例，
+也不是 Signal。概念结构：Identity / Universe / Factors / Screener /
+Entry / Exit / Holding / PositionIntent / Parameters。
+
+生命周期（StrategyStatus）描述 Artifact 状态；运行环境（StrategyRunMode）
+单独定义——同一 Definition 在 Backtest / Paper / Live 下业务逻辑不变。
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.strategy.constants import (
+    AuthoringSource,
+    StrategyStatus,
+    StrategyStyle,
+    StrategyType,
+)
+
+# V1 规则操作符（受限谓词，由 Runtime 解释；不引入通用表达式引擎）
+RuleOperator = Literal["gt", "gte", "lt", "lte", "cross_below", "cross_above"]
+
+
+class RuleCondition(BaseModel):
+    """单条规则条件：factor 因子值（或 close/volume 等价格字段）与阈值/参照比较"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    left: str = Field(..., description="左值：因子名或价格字段（close/volume/ma_10...）")
+    operator: RuleOperator = Field(..., description="比较操作")
+    right: str | float = Field(..., description="右值：数值或另一因子/字段名")
+
+
+class ScreenerSpec(BaseModel):
+    """策略内嵌筛选说明（声明式；执行归属 Screener 能力）"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    filters: list[RuleCondition] = Field(default_factory=list, description="过滤条件（全部满足）")
+    rank_by: str | None = Field(default=None, description="排名因子/字段（降序）")
+    top_n: int = Field(default=10, ge=1, description="取前 N")
+
+
+class StrategyDefinition(BaseModel):
+    """策略定义（Artifact）——Human / Agent / Python 都生产同一个 Canonical Definition"""
+
+    model_config = ConfigDict(validate_assignment=True)
+
+    strategy_id: str = Field(..., pattern=r"^[a-z][a-z0-9_]*$", description="策略标识（唯一键）")
+    version: str = Field(default="1", description="策略版本")
+    name: str = Field(..., description="策略名称")
+    description: str = Field(default="", description="策略说明")
+    strategy_type: StrategyType = Field(..., description="决策范式")
+    styles: list[str] = Field(default_factory=list, description="风格 Tag（StrategyStyle 值）")
+    universe: list[str] = Field(default_factory=list, description="标的池(Canonical ID)")
+    required_factors: list[str] = Field(default_factory=list, description="依赖因子名")
+    screening_rules: ScreenerSpec | None = Field(default=None, description="筛选/排名说明")
+    entry_rules: list[RuleCondition] = Field(default_factory=list, description="入场条件，全部满足")
+    exit_rules: list[RuleCondition] = Field(default_factory=list, description="出场条件，任一满足")
+    holding_rules: list[str] = Field(default_factory=list, description="持仓管理规则，V1 描述性")
+    position_intent: Literal["long_only", "long_short", "target_weight"] = Field(
+        default="long_only", description="持仓意图（A股 V1：long_only）"
+    )
+    parameters: dict[str, Any] = Field(default_factory=dict, description="策略参数")
+    status: StrategyStatus = Field(default=StrategyStatus.DRAFT, description="Artifact 生命周期")
+    authoring_source: AuthoringSource = Field(default=AuthoringSource.HUMAN, description="生产入口")
+    created_by: str | None = Field(default=None, description="生产者标识（可追溯）")
+    parent_version: str | None = Field(default=None, description="迭代自哪个版本（Agent 迭代链）")
+    implementation_ref: str | None = Field(
+        default=None, description="Python Native 实现引用（dotted path，显式关联不靠文件名）"
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict, description="扩展元数据")
+
+    def validate_definition(self, registered_factors: set[str] | None = None) -> list[str]:
+        """Definition Validation（静态层），返回问题列表
+
+        registered_factors：可选传入已注册因子名集合，校验 required_factors 引用合法。
+        """
+        problems: list[str] = []
+        if not self.entry_rules and not self.exit_rules:
+            problems.append("entry_rules 与 exit_rules 至少定义一组")
+        valid_styles = {s.value for s in StrategyStyle}
+        for style in self.styles:
+            if style not in valid_styles:
+                problems.append(f"非法 style: {style}")
+        for cond in [*self.entry_rules, *self.exit_rules]:
+            if not cond.left.strip():
+                problems.append("规则条件 left 不能为空")
+        if registered_factors is not None:
+            for name in self.required_factors:
+                if name not in registered_factors:
+                    problems.append(f"required_factors 引用未注册因子: {name}")
+        return problems

quant_core/app/strategy/service/factor_top_n_strategy.py

@@ -0,0 +1,103 @@
+"""内置多因子链的单因子 TopN 配置：共享评分、目标组合与调仓。"""
+
+from datetime import date
+from decimal import Decimal
+from typing import Literal
+
+from quant_core.app.data.schema.event_schema import BarEvent, MarketTimeSlice, TradingSessionEvent
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+from quant_core.app.factor.schema.selection_types import FactorWeight, SelectionDefinition
+from quant_core.app.strategy.schema.portfolio_target import PortfolioConstraints, PortfolioDecision
+from quant_core.app.strategy.schema.signal_schema import Signal
+from quant_core.app.strategy.schema.strategy_schema import StrategyDefinition, StrategyType
+from quant_core.app.strategy.strategy_context import StrategyContext
+
+
+class FactorTopNStrategy:
+    """每个交易日首个可观察 Bar 时间片构造一次目标；持仓事实只从账户读取。"""
+
+    def __init__(
+        self,
+        universe: tuple[str, ...],
+        identity: FactorIdentity,
+        top_n: int,
+        constraints: PortfolioConstraints,
+        strategy_id: str = "factor_top_n",
+        rebalance_period: Literal["daily", "weekly"] = "daily",
+    ) -> None:
+        self._universe = universe
+        self._identity = identity
+        self._selection = SelectionDefinition((FactorWeight(identity, Decimal(1)),), top_n)
+        self._constraints = constraints
+        self._strategy_id = strategy_id
+        self._last_day: date | None = None
+        self._rebalance_period = rebalance_period
+
+    def definition(self) -> StrategyDefinition:
+        return StrategyDefinition(
+            strategy_id=self._strategy_id,
+            name="Factor Top-N Target Portfolio",
+            strategy_type=StrategyType.EVENT_DRIVEN,
+            universe=list(self._universe),
+            required_factors=[self._identity.name],
+            parameters={
+                "top_n": self._selection.top_n,
+                "cash_buffer": str(self._constraints.cash_buffer),
+                "max_weight": str(self._constraints.max_weight),
+            },
+        )
+
+    async def on_bar(self, event: BarEvent, context: StrategyContext) -> list[Signal]:
+        return []
+
+    async def on_session(
+        self, event: TradingSessionEvent, context: StrategyContext
+    ) -> list[Signal]:
+        return []
+
+    async def on_slice(self, time_slice: MarketTimeSlice, context: StrategyContext) -> list[Signal]:
+        day = time_slice.event_time.date()
+        if self._last_day == day or not any(
+            isinstance(event, BarEvent) for event in time_slice.events
+        ):
+            return []
+        if (
+            self._rebalance_period == "weekly"
+            and self._last_day is not None
+            and self._last_day.isocalendar()[:2] == day.isocalendar()[:2]
+        ):
+            return []
+        if context.portfolio is None:
+            raise RuntimeError("组合策略必须提供真实账户读取能力")
+        account = await context.portfolio.get_snapshot()
+        current_weights = {
+            position.instrument_id: position.market_value / account.total_value
+            for position in account.positions
+            if account.total_value > 0
+        }
+        holding_sessions = {}
+        if self._constraints.min_holding_sessions:
+            acquired = {}
+            for lot in await context.portfolio.get_position_lots():
+                if lot.remaining_quantity:
+                    acquired[lot.instrument_id] = max(
+                        acquired.get(lot.instrument_id, lot.acquired_at.date()),
+                        lot.acquired_at.date(),
+                    )
+            for instrument_id, acquired_on in acquired.items():
+                calendar = await context.market.list_trading_days("XSHG", acquired_on, day)
+                holding_sessions[instrument_id] = sum(
+                    item.is_open and acquired_on < item.trade_date <= day for item in calendar
+                )
+        selection = context.select_factors(self._selection)
+        target = context.construct_portfolio(
+            selection,
+            self._constraints,
+            current_weights=current_weights,
+            holding_sessions=holding_sessions,
+        )
+        context.order_target_portfolio(
+            dict(target.weights), decision=PortfolioDecision(selection, target, self._constraints)
+        )
+        self._last_day = day
+        return []