powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/strategy/service/portfolio_construction_service.py

@@ -0,0 +1,142 @@
+"""等权目标组合及显式风险约束；资金占用、T+1 与成交归后续执行链。"""
+
+from decimal import ROUND_DOWN, Decimal
+
+from quant_core.app.factor.schema.selection_types import SelectionResult
+from quant_core.app.strategy.schema.portfolio_target import PortfolioConstraints, TargetPortfolio
+
+
+class PortfolioConstructionService:
+    def build(
+        self,
+        selection: SelectionResult,
+        constraints: PortfolioConstraints,
+        *,
+        current_weights: dict[str, Decimal] | None = None,
+        industries: dict[str, str] | None = None,
+        holding_sessions: dict[str, int] | None = None,
+    ) -> TargetPortfolio:
+        """约束后的未分配预算留现金，不隐式放松上限或补选证券。"""
+        if current_weights is not None and (
+            any(not weight.is_finite() or weight < 0 for weight in current_weights.values())
+            or sum(current_weights.values(), Decimal(0)) > 1
+        ):
+            raise ValueError("当前账户权重非法")
+        if holding_sessions is not None and any(age < 0 for age in holding_sessions.values()):
+            raise ValueError("持仓交易日龄不得为负")
+        scores = {item.instrument_id: item.score for item in selection.selected}
+        scores.update(
+            {
+                item.instrument_id: item.score
+                for item in selection.excluded
+                if item.reason == "top_n" and item.score is not None
+            }
+        )
+        ranked = sorted(scores, key=lambda key: (-scores[key], key))
+        capacity = min(constraints.max_positions, len(selection.selected))
+        held = {key for key, weight in (current_weights or {}).items() if weight > 0}
+        reasons: list[str] = []
+        selected: list[str] = []
+        retention_enabled = (
+            constraints.retention_rank is not None
+            or constraints.max_replacements is not None
+            or constraints.min_holding_sessions > 0
+        )
+        if retention_enabled and current_weights is None:
+            raise ValueError("持仓保留规则需要当前真实账户权重")
+        if constraints.min_holding_sessions:
+            if holding_sessions is None or held - holding_sessions.keys():
+                raise ValueError("最低持有期需要真实持仓批次的交易日龄")
+            selected = sorted(
+                key for key in held if holding_sessions[key] < constraints.min_holding_sessions
+            )
+            reasons.extend(f"minimum_holding:{key}" for key in selected)
+        if len(selected) > constraints.max_positions:
+            raise ValueError("最低持有期与最大持仓数冲突")
+        capacity = max(capacity, len(selected))
+        retained = [key for key in ranked if key in held]
+        if constraints.retention_rank is not None:
+            for key in ranked[: constraints.retention_rank]:
+                if key in held and key not in selected and len(selected) < capacity:
+                    selected.append(key)
+                    reasons.append(f"retained_rank:{key}")
+        if constraints.max_replacements is not None:
+            keep_count = max(0, len(retained) - constraints.max_replacements)
+            for key in retained:
+                if len(set(selected) & held) >= keep_count or len(selected) >= capacity:
+                    break
+                if key not in selected:
+                    selected.append(key)
+                    reasons.append(f"replacement_limit:{key}")
+            reasons.extend(
+                f"forced_exit_missing_or_filtered:{key}"
+                for key in sorted(held - set(ranked) - set(selected))
+            )
+        for key in ranked:
+            if len(selected) >= capacity:
+                break
+            if key not in selected:
+                selected.append(key)
+        weights: dict[str, Decimal] = {}
+        if selected:
+            per_stock = min(
+                (Decimal(1) - constraints.cash_buffer) / len(selected), constraints.max_weight
+            )
+            weights = {
+                key: per_stock.quantize(Decimal("1e-18"), rounding=ROUND_DOWN) for key in selected
+            }
+        if constraints.industry_caps:
+            if set(weights) - (industries or {}).keys():
+                raise ValueError("行业上限缺少证券行业信息")
+            for industry, cap in constraints.industry_caps:
+                members = [key for key in weights if (industries or {})[key] == industry]
+                total = sum((weights[key] for key in members), Decimal(0))
+                if total > cap:
+                    for key in members:
+                        weights[key] = (weights[key] * cap / total).quantize(
+                            Decimal("1e-18"), rounding=ROUND_DOWN
+                        )
+                    reasons.append(f"industry_cap:{industry}")
+        if constraints.max_turnover is not None:
+            if current_weights is None:
+                raise ValueError("换手约束必须提供当前账户权重")
+            union = weights.keys() | current_weights.keys()
+            changes = {
+                key: weights.get(key, Decimal(0)) - current_weights.get(key, Decimal(0))
+                for key in union
+            }
+            turnover = max(
+                sum((max(delta, Decimal(0)) for delta in changes.values()), Decimal(0)),
+                sum((max(-delta, Decimal(0)) for delta in changes.values()), Decimal(0)),
+            )
+            if turnover > constraints.max_turnover:
+                scale = constraints.max_turnover / turnover
+                weights = {
+                    key: current_weights.get(key, Decimal(0)) + change * scale
+                    for key, change in changes.items()
+                }
+                reasons.append("turnover_cap")
+        weights = {key: weight for key, weight in weights.items() if weight > 0}
+        cash = Decimal(1) - sum(weights.values(), Decimal(0))
+        if (
+            len(weights) > constraints.max_positions
+            or any(weight > constraints.max_weight for weight in weights.values())
+            or cash < constraints.cash_buffer
+        ):
+            raise ValueError("换手约束与持仓/现金上限冲突，无法构造合法目标")
+        for industry, cap in constraints.industry_caps:
+            if set(weights) - (industries or {}).keys():
+                raise ValueError("保留持仓缺少行业信息")
+            if (
+                sum(
+                    (
+                        weight
+                        for key, weight in weights.items()
+                        if (industries or {})[key] == industry
+                    ),
+                    Decimal(0),
+                )
+                > cap
+            ):
+                raise ValueError("换手约束与行业上限冲突")
+        return TargetPortfolio(tuple(sorted(weights.items())), cash, tuple(reasons))

quant_core/app/strategy/service/python_strategy_service.py

@@ -0,0 +1,65 @@
+"""One loading path for persisted and temporary trusted Python strategies."""
+
+import inspect
+from typing import Any
+
+from quant_core.app.strategy.constants import StrategyType
+from quant_core.app.strategy.schema.python_strategy_schema import PythonStrategySpec
+from quant_core.app.strategy.schema.strategy_schema import StrategyDefinition
+
+
+class PythonStrategy:
+    """Adapt module-level callbacks to the existing Strategy Runtime contract."""
+
+    def __init__(self, spec: PythonStrategySpec, universe: tuple[str, ...] = ()) -> None:
+        spec.validate_source()
+        self.spec = spec
+        self._universe = universe or spec.universe
+        namespace: dict[str, Any] = {"__name__": "strategy_user_code"}
+        exec(compile(spec.python_source, "<strategy>", "exec"), namespace)
+        self._callbacks = namespace
+
+    def definition(self) -> StrategyDefinition:
+        return StrategyDefinition(
+            strategy_id=self.spec.strategy_id,
+            version=self.spec.version,
+            name=self.spec.name,
+            description=self.spec.description,
+            strategy_type=StrategyType.EVENT_DRIVEN,
+            universe=list(self._universe),
+            required_factors=list(self.spec.resolved_factors()),
+            parameters=dict(self.spec.parameters),
+        )
+
+    async def _call(self, name: str, *args: Any) -> list:
+        callback = self._callbacks.get(name)
+        if callback is None:
+            return []
+        result = callback(*args)
+        if inspect.isawaitable(result):
+            result = await result
+        return list(result or ())
+
+    async def on_bar(self, event, context) -> list:
+        return await self._call("on_bar", event, context)
+
+    async def init(self, context) -> list:
+        return await self._call("init", context)
+
+    async def on_slice(self, time_slice, context) -> list:
+        if "handle_bar" in self._callbacks:
+            from quant_core.app.data.schema.event_schema import BarEvent
+
+            if any(isinstance(event, BarEvent) for event in time_slice.events):
+                return await self._call("handle_bar", context, context.current_data)
+            return []
+        return await self._call("on_slice", time_slice, context)
+
+    async def on_session(self, event, context) -> list:
+        return await self._call("on_session", event, context)
+
+    async def before_trading(self, context) -> list:
+        return await self._call("before_trading", context)
+
+    async def after_trading(self, context) -> list:
+        return await self._call("after_trading", context)

quant_core/app/strategy/service/screener_service.py

@@ -0,0 +1,77 @@
+"""
+Screener Service - 从 Universe 中筛选和排名候选标的
+
+链路：Universe → Factor Values → Filter → Rank → Top N → ScreenerResult。
+运行契约就是 Canonical `ScreenerSpec`（来自 StrategyDefinition.screening_rules）——
+Definition 是 Runtime 的真实输入契约，不存在第二套临时 dict 模型。
+纯内存运算：输入是已算好的 Canonical FactorValue（因子计算归属 FactorRuntime，
+R2-1：唯一因子值形态），本 Service 不取数、不算因子。
+"""
+
+from decimal import Decimal
+
+from quant_core.app.factor.constants import FactorStatus as CanonicalFactorStatus
+from quant_core.app.factor.schema.factor_contract import FactorValue
+from quant_core.app.strategy.exceptions import StrategyValidationException
+from quant_core.app.strategy.schema.screener_schema import (
+    ScreenerCandidate,
+    ScreenerRequest,
+    ScreenerResult,
+)
+from quant_core.app.strategy.schema.strategy_schema import RuleCondition
+
+
+def screen(request: ScreenerRequest) -> ScreenerResult:
+    """过滤（全部满足）→ 按 spec.rank_by 降序 → 取前 spec.top_n
+
+    因子值缺失（None/非 AVAILABLE/未算）的标的被过滤掉，不参与排名。
+    """
+    spec = request.spec
+    ranked: list[ScreenerCandidate] = []
+    for instrument_id in request.universe:
+        values: dict[str, Decimal | None] = {}
+        for factor_name in request.factor_values:
+            result = _find(request.factor_values[factor_name], instrument_id)
+            values[factor_name] = (
+                result.value
+                if result and result.status is CanonicalFactorStatus.AVAILABLE
+                else None
+            )
+        if not all(_satisfied(c, values) for c in spec.filters):
+            continue
+        score = values.get(spec.rank_by or "")
+        if score is None:
+            continue
+        ranked.append(
+            ScreenerCandidate(instrument_id=instrument_id, score=score, factor_values=values)
+        )
+    ranked.sort(key=lambda c: c.score, reverse=True)
+    return ScreenerResult(
+        event_time=request.event_time,
+        candidates=ranked[: spec.top_n],
+        metadata={"universe_size": len(request.universe), "filter_count": len(spec.filters)},
+    )
+
+
+def _satisfied(condition: RuleCondition, values: dict[str, Decimal | None]) -> bool:
+    """单条 RuleCondition 求值（左值 = 因子值；右值仅支持数值字面量）"""
+    left = values.get(condition.left)
+    if left is None:
+        return False
+    if not isinstance(condition.right, (int, float)):
+        raise StrategyValidationException(f"V1 Screener 仅支持数值阈值: {condition.right}")
+    right = Decimal(str(condition.right))
+    op = condition.operator
+    if op == "gt":
+        return left > right
+    if op == "gte":
+        return left >= right
+    if op == "lt":
+        return left < right
+    if op == "lte":
+        return left <= right
+    raise StrategyValidationException(f"Screener 未支持的操作符: {op}")
+
+
+def _find(results: list[FactorValue], instrument_id: str) -> FactorValue | None:
+    return next((r for r in results if r.instrument_id == instrument_id), None)

quant_core/app/strategy/service/store_factor_reader.py

@@ -0,0 +1,120 @@
+"""Strategy 消费已发布 Factor Store 的只读桥。
+
+Factor 身份、修订和新鲜度由组装点指定；缺行显式返回 MISSING，
+不会回退其他来源或版本，也不在 Strategy 内计算因子。
+"""
+
+from datetime import datetime, time
+from zoneinfo import ZoneInfo
+
+from quant_core.app.factor.constants import FactorFreshness, FactorSourceKind, FactorStatus
+from quant_core.app.factor.exceptions import InsufficientFactorHistoryError
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import (
+    FactorIdentity,
+    FactorProvenance,
+    FactorValue,
+)
+
+_CN = ZoneInfo("Asia/Shanghai")
+
+
+class StoreFactorReader:
+    """按显式身份读取 Canonical Factor Store 的 PIT 值。"""
+
+    def __init__(
+        self,
+        query: IFactorQuery | None,
+        identities: dict[str, FactorIdentity],
+        *,
+        dataset_revision: str | None = None,
+        freshness: FactorFreshness = FactorFreshness.EXACT,
+    ) -> None:
+        if identities and query is None:
+            raise ValueError("声明因子依赖时必须提供 Factor Query")
+        self._query = query
+        self._identities = dict(identities)
+        self._dataset_revision = dataset_revision
+        self._freshness = freshness
+        self._cache: dict[tuple[datetime, str, str], FactorValue] = {}
+
+    async def read_many(
+        self,
+        factor_names: tuple[str, ...],
+        instrument_ids: tuple[str, ...],
+        decision_time: datetime,
+    ) -> dict[str, dict[str, FactorValue]]:
+        """一次读取完整截面，缓存仅保留当前决策时点，避免按格查询。"""
+        unknown = set(factor_names) - self._identities.keys()
+        if unknown:
+            raise ValueError(f"因子未在 StoreFactorReader 显式声明身份: {sorted(unknown)}")
+        if not factor_names or not instrument_ids:
+            return {}
+        self._cache = {key: value for key, value in self._cache.items() if key[0] == decision_time}
+        missing = [
+            (name, iid)
+            for name in factor_names
+            for iid in instrument_ids
+            if (decision_time, name, iid) not in self._cache
+        ]
+        if missing:
+            assert self._query is not None
+            identities = list(dict.fromkeys(self._identities[name] for name, _ in missing))
+            instruments = sorted({iid for _, iid in missing})
+            try:
+                snapshot = await self._query.get_snapshot(
+                    identities,
+                    instruments,
+                    decision_time,
+                    freshness=self._freshness,
+                    dataset_revision=self._dataset_revision,
+                )
+                cells = {(row.identity, row.instrument_id): row for row in snapshot.values}
+                if len(cells) != len(snapshot.values):
+                    raise ValueError("因子截面同格多行，拒绝隐式覆盖")
+            except InsufficientFactorHistoryError:
+                cells = {}
+            for name, iid in missing:
+                identity = self._identities[name]
+                value = cells.get((identity, iid))
+                self._cache[(decision_time, name, iid)] = (
+                    value if value is not None else self._missing_row(identity, iid, decision_time)
+                )
+        return {
+            name: {iid: self._cache[(decision_time, name, iid)] for iid in instrument_ids}
+            for name in factor_names
+        }
+
+    async def read(
+        self,
+        factor_name: str,
+        instrument_id: str,
+        decision_time: datetime,
+    ) -> FactorValue:
+        """单格查询复用批量查询契约。"""
+        rows = await self.read_many((factor_name,), (instrument_id,), decision_time)
+        return rows[factor_name][instrument_id]
+
+    @staticmethod
+    def _missing_row(
+        identity: FactorIdentity, instrument_id: str, event_time: datetime
+    ) -> FactorValue:
+        """Store 无行的显式缺失行（value=None；不冒充任何 Provider 产出）
+
+        as_of = available_at 取决策日 CN 零点，区别于真实日线归属时间。
+        """
+        midnight = datetime.combine(event_time.astimezone(_CN).date(), time.min, tzinfo=_CN)
+        return FactorValue(
+            identity=identity,
+            instrument_id=instrument_id,
+            as_of=midnight,
+            available_at=midnight,
+            value=None,
+            status=FactorStatus.MISSING,
+            provenance=FactorProvenance(
+                source_kind=FactorSourceKind.EXTERNAL_PROVIDER,
+                provider_id="factor-store",
+                note="store 无该格数据行（合成 MISSING，非 Provider 产出）",
+                dataset_revision=None,
+            ),
+        )

quant_core/app/strategy/service/strategy_market_view.py

@@ -0,0 +1,120 @@
+"""Strategy 专用价格视图：锁定决策时点动态前复权，禁止旁路读取 raw 历史。"""
+
+from collections.abc import Sequence
+from datetime import date, datetime
+
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.data.schema.adjustment_schema import (
+    AdjustedBarSeries,
+    AdjustmentAnchorMode,
+    AdjustmentType,
+    BarViewRequest,
+)
+from quant_core.app.data.schema.market_schema import (
+    BarResponse,
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+)
+
+
+class StrategyMarketView:
+    """把 IMarketDataQuery 收窄为当前决策时点的 Strategy 观察面。"""
+
+    def __init__(
+        self,
+        market: IMarketDataQuery,
+        decision_time: datetime,
+        adjustment_type: AdjustmentType,
+    ) -> None:
+        self._market = market
+        self._decision_time = decision_time
+        self._adjustment_type = adjustment_type
+
+    async def get_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> Sequence[BarResponse]:
+        if end is not None and end > self._decision_time:
+            raise ValueError("Strategy 行情窗口 end 不得晚于当前 decision_time")
+        if self._adjustment_type is AdjustmentType.NONE:
+            return await self._market.get_bars(
+                instrument_id, frequency, start, end or self._decision_time, limit
+            )
+        series = await self.get_adjusted_bars(
+            instrument_id,
+            frequency,
+            BarViewRequest(
+                adjustment_type=self._adjustment_type,
+                anchor_mode=AdjustmentAnchorMode.DECISION_TIME,
+                decision_time=self._decision_time,
+            ),
+            start,
+            end or self._decision_time,
+            limit,
+        )
+        return series.bars
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime | None = None,
+        end: datetime | None = None,
+        limit: int = 1000,
+    ) -> AdjustedBarSeries:
+        if view.adjustment_type is not self._adjustment_type:
+            raise ValueError("Strategy 不得覆盖 Backtest 锁定的 adjustment_type")
+        if view.anchor_mode is not AdjustmentAnchorMode.DECISION_TIME:
+            raise ValueError("Strategy 回测只允许 DECISION_TIME 动态锚点")
+        if view.decision_time != self._decision_time:
+            raise ValueError("Strategy 不得覆盖当前 decision_time")
+        if end is not None and end > self._decision_time:
+            raise ValueError("Strategy 行情窗口 end 不得晚于当前 decision_time")
+        return await self._market.get_adjusted_bars(
+            instrument_id,
+            frequency,
+            view,
+            start,
+            end or self._decision_time,
+            limit,
+        )
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse:
+        item = await self._market.get_instrument(instrument_id)
+        if item.listed_date is not None and item.listed_date > self._decision_time.date():
+            raise ValueError("当前决策时点不可见未来上市标的")
+        return item
+
+    async def list_instruments_on(
+        self, on_date: date, limit: int = 10000
+    ) -> list[InstrumentResponse]:
+        if on_date > self._decision_time.date():
+            raise ValueError("股票池日期不得晚于当前决策日期")
+        return await self._market.list_instruments_on(on_date, limit)
+
+    async def search_instruments(
+        self,
+        keyword: str | None = None,
+        instrument_type: str | None = None,
+        exchange: str | None = None,
+        limit: int = 100,
+    ) -> list[InstrumentResponse]:
+        items = await self._market.search_instruments(keyword, instrument_type, exchange, limit)
+        return [
+            item
+            for item in items
+            if item.listed_date is None or item.listed_date <= self._decision_time.date()
+        ]
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool:
+        return await self._market.is_trading_day(exchange, trade_date)
+
+    async def list_trading_days(
+        self, exchange: str, start: date, end: date
+    ) -> list[TradingCalendarDayResponse]:
+        return await self._market.list_trading_days(exchange, start, end)