powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/factor/service/factor_runtime_service.py

@@ -0,0 +1,306 @@
+"""Factor Runtime Query Service（T4）——离线、point-in-time 安全的因子查询面
+
+语义（T4 Task AC + R2-5/R2-6）：
+- 消费面只依赖 T2 Store Protocol（不联网、不依赖 Provider 类型）；
+- resolve_window：lookback 按交易日确定性解析（anchor 必须是交易日；
+  含 anchor 当日、往回 lookback-1 个交易日），日历不足结构化报错；
+- get_snapshot：显式 target_as_of + freshness 策略（R2-5，T5 前裁定）——
+  默认 EXACT：只消费目标业务日的值，目标日无值绝不因历史旧值冒充
+  PRESENT；LATEST_KNOWN：显式回退最近可得历史值，覆盖报告标注 stale；
+  输入顺序归一（排序+去重）后透传 Store；Store 层强制
+  available_at <= decision_time（T2/T1 PIT 门禁）；
+- coverage_report：逐 identity×instrument 输出封闭枚举 FactorCoverageState
+  （R1-4）：PRESENT / MISSING / UNAVAILABLE / NOT_YET_PUBLISHED；空请求
+  结构化拒绝（R2-6：空 cells 上 all() 为 True 的假 complete 不允许）；
+  未发布/缺失的区分用 Store 显式 probe_status 存在性/状态查询（R2-6，
+  替代任意 +3650 天远期探针），只读 status、不产生决策可见值；
+- 相同请求（含输入顺序变化）输出确定性一致（T1 Snapshot 自身归一保证）；
+- 本 Service 真实结构满足 IFactorQuery（R1-1，isinstance 守护）。
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from quant_core.app.factor.constants import (
+    FactorCoverageState,
+    FactorFreshness,
+    FactorStatus,
+)
+from quant_core.app.factor.exceptions import (
+    InsufficientFactorHistoryError,
+    InvalidFactorRangeError,
+)
+from quant_core.app.factor.interface.factor_query_store import IFactorQueryStore
+from quant_core.app.factor.schema.factor_contract import (
+    FactorIdentity,
+    FactorSnapshot,
+    FactorSnapshotSelection,
+    FactorValue,
+)
+from quant_core.app.factor.schema.factor_query_result_schema import ProbeCellStatus
+from quant_core.app.factor.visibility import next_trading_day_open
+
+
+@dataclass(frozen=True)
+class CoverageState:
+    """单 identity×instrument 的覆盖状态（封闭枚举，R1-4；R2-5 新鲜度证据）
+
+    - value_as_of：实际消费值的归属业务日（PRESENT 时有值）；
+    - stale：LATEST_KNOWN 回退消费了早于 target_as_of 的旧值（EXACT 下恒
+      False——EXACT 不回退，旧值不进快照）。
+    """
+
+    state: FactorCoverageState
+    value_as_of: date | None = None
+    stale: bool = False
+
+
+@dataclass(frozen=True)
+class FactorCoverageReport:
+    """截面覆盖报告（键：identity.logical_key × instrument_id）
+
+    complete 仅在全部格子 PRESENT 且无 stale 回退时为 True——MISSING/
+    UNAVAILABLE/NOT_YET_PUBLISHED 一律不算完整（R1-4/R2-5）。
+    """
+
+    cells: dict[tuple[tuple, str], CoverageState]
+    target_as_of: date
+
+    @property
+    def complete(self) -> bool:
+        return all(
+            c.state is FactorCoverageState.PRESENT and not c.stale for c in self.cells.values()
+        )
+
+
+class FactorRuntimeService:
+    """因子运行时查询（Strategy/Backtest 唯一因子消费面）"""
+
+    def __init__(
+        self,
+        query: IFactorQueryStore,
+        trading_days: list[date],
+    ) -> None:
+        self._query = query
+        self._trading_days = sorted(trading_days)
+
+    # ------------------------------------------------------------------
+    # lookback / warmup 解析
+    # ------------------------------------------------------------------
+
+    def resolve_window(self, anchor: date, lookback: int) -> tuple[date, date]:
+        """warmup 语义：anchor 往回 lookback 个交易日 + anchor 当日 → [start, end]
+
+        确定性：同一 (anchor, lookback) 恒等映射；anchor 非交易日或日历
+        不足 → InsufficientFactorHistoryError（不静默截断）。
+        """
+        if lookback < 1:
+            raise InvalidFactorRangeError(f"lookback 必须 ≥1，收到 {lookback}")
+        days = self._trading_days
+        try:
+            pos = days.index(anchor)
+        except ValueError:
+            raise InsufficientFactorHistoryError(
+                f"anchor {anchor} 不是交易日（或不在日历范围内）"
+            ) from None
+        start_pos = pos - lookback
+        if start_pos < 0:
+            raise InsufficientFactorHistoryError(
+                f"交易日历不足：anchor {anchor} 往回 {lookback} 个交易日越界"
+            )
+        return days[start_pos], days[pos]
+
+    def resolve_target_as_of(self, decision_time: datetime) -> date:
+        """EXACT 默认目标业务日 = 已完整发布的最新因子日
+
+        日频因子 as_of = 当日收盘（15:00），最早可见于下一交易日 09:30
+        （Q2=A）——因此目标日是「下一交易日开盘 ≤ decision_time」的最近
+        交易日（严格早于 decision 当日的上一个交易日）；日历无先行日 →
+        结构化报错。
+        """
+        target = None
+        for d in self._trading_days:
+            nxt = next_trading_day_open(d, self._trading_days)
+            if nxt is not None and nxt <= decision_time:
+                target = d
+        if target is None:
+            raise InsufficientFactorHistoryError(
+                f"交易日历中不存在 {decision_time} 前已完整发布的因子日，无法确定目标业务日"
+            )
+        return target
+
+    # ------------------------------------------------------------------
+    # 截面 / 序列查询
+    # ------------------------------------------------------------------
+
+    async def get_snapshot(
+        self,
+        identities: list[FactorIdentity],
+        instrument_ids: list[str],
+        decision_time: datetime,
+        *,
+        target_as_of: date | None = None,
+        freshness: FactorFreshness = FactorFreshness.EXACT,
+        dataset_revision: str | None = None,
+    ) -> FactorSnapshot:
+        """decision_time 可见截面（R2-5：目标业务日 + 新鲜度策略）
+
+        - EXACT（默认）：只取 target_as_of 当日的值（Store as_of_on 过滤），
+          目标日无值不回退旧值；
+        - LATEST_KNOWN：显式回退——取可见的最高修订 × 最新 as_of（不早于
+          语义由 Store 的可见性谓词保证），stale 由 coverage_report 标注；
+        - dataset_revision：pin 旧数据集修订复现旧回测（R2-2）。
+        """
+        target = target_as_of or self.resolve_target_as_of(decision_time)
+        norm_ids = sorted(set(instrument_ids))
+        norm_idents = sorted(set(identities), key=lambda i: i.logical_key)
+        rows = await self._query.list_snapshot(
+            tuple(norm_idents),
+            tuple(norm_ids),
+            decision_time,
+            dataset_revision=dataset_revision,
+            as_of_on=target if freshness is FactorFreshness.EXACT else None,
+        )
+        return FactorSnapshot(
+            values=tuple(rows),
+            decision_time=decision_time,
+            selection=FactorSnapshotSelection(
+                identities=tuple(norm_idents),
+                instrument_ids=tuple(norm_ids),
+                target_as_of=target,
+                freshness=freshness,
+                dataset_revision=dataset_revision,
+            ),
+        )
+
+    async def get_series(
+        self,
+        identity: FactorIdentity,
+        instrument_id: str,
+        start: datetime,
+        end: datetime,
+        decision_time: datetime,
+        *,
+        dataset_revision: str | None = None,
+    ) -> tuple[FactorValue, ...]:
+        """单因子×单标的 [start, end] 可见历史（start > end 拒绝；R2-2 pin）"""
+        if start > end:
+            raise InvalidFactorRangeError(f"start {start} 晚于 end {end}")
+        return await self._query.list_series(
+            identity, instrument_id, start, end, decision_time, dataset_revision=dataset_revision
+        )
+
+    # ------------------------------------------------------------------
+    # 覆盖报告
+    # ------------------------------------------------------------------
+
+    async def coverage_report(
+        self,
+        snapshot: FactorSnapshot,
+        identities: list[FactorIdentity],
+        instrument_ids: list[str],
+        decision_time: datetime,
+        *,
+        target_as_of: date | None = None,
+        freshness: FactorFreshness | None = None,
+        dataset_revision: str | None = None,
+    ) -> FactorCoverageReport:
+        """逐格输出封闭枚举覆盖状态（R1-4/R2-5/R2-6/R3 P1-2/P1-4）
+
+        - 空请求结构化拒绝（R2-6：空 cells 上 all()→True 的假 complete）；
+        - R3 P1-2：snapshot.decision_time 必须等于 decision_time——报告只
+          基于同一时点可见行生成，未来快照不得回传过去决策时点；
+        - EXACT：只认目标业务日的可见行——目标日无值一律不 PRESENT
+          （历史旧值不回退）；LATEST_KNOWN：回退旧值时标 stale + value_as_of；
+        - 可见行 AVAILABLE → PRESENT；只有 UNAVAILABLE → UNAVAILABLE；
+          缺格进入 Store probe_status 同格探查（R3 P1-4：证据只来自目标
+          业务日 + 修订选择的同一批行，不聚合跨日状态）：目标日存在
+          AVAILABLE/NOT_YET_PUBLISHED 数据行 → NOT_YET_PUBLISHED；目标日
+          数据本身就是 MISSING/UNAVAILABLE → 如实保留；目标日无行 → MISSING。
+        - 探查结果只进报告，不进 snapshot（不产生决策可见值）。
+        - 省略 target_as_of/freshness/dataset_revision 时继承 Snapshot 的冻结
+          选择上下文；显式给出非 None 值只能与原选择一致，不能重解释截面。
+        """
+        if not identities or not instrument_ids:
+            raise ValueError("coverage_report 拒绝空请求（identities/instrument_ids 不得为空）")
+        # R3 P1-2：报告绑定同一时点的 Snapshot——未来时点快照回传过去决策时点
+        # 会泄漏 PIT 覆盖资格与完整性（Snapshot 自身构造门只约束它自己的
+        # decision_time，不约束调用方传入的判定时点）
+        if snapshot.decision_time != decision_time:
+            raise ValueError(
+                f"snapshot.decision_time {snapshot.decision_time} 与报告 "
+                f"decision_time {decision_time} 不一致（覆盖报告只接受同一时点的快照）"
+            )
+        selection = snapshot.selection
+        if selection is None:
+            raise ValueError("snapshot 缺少查询选择上下文，不能生成覆盖报告")
+        if selection.identities != tuple(sorted(set(identities), key=lambda i: i.logical_key)):
+            raise ValueError("snapshot identities 与覆盖请求不一致")
+        if selection.instrument_ids != tuple(sorted(set(instrument_ids))):
+            raise ValueError("snapshot instrument_ids 与覆盖请求不一致")
+        if target_as_of is not None and selection.target_as_of != target_as_of:
+            raise ValueError("snapshot target_as_of 与覆盖请求不一致")
+        if freshness is not None and selection.freshness is not freshness:
+            raise ValueError("snapshot freshness 与覆盖请求不一致")
+        if dataset_revision is not None and selection.dataset_revision != dataset_revision:
+            raise ValueError("snapshot dataset_revision 与覆盖请求不一致")
+        target = selection.target_as_of
+        freshness = selection.freshness
+        dataset_revision = selection.dataset_revision
+        want = {(i.logical_key, inst) for i in identities for inst in instrument_ids}
+        by_cell: dict[tuple[tuple, str], dict[date, set]] = {}
+        for v in snapshot.values:
+            key = (v.identity.logical_key, v.instrument_id)
+            if key not in want:
+                continue
+            if freshness is FactorFreshness.EXACT and v.as_of.date() != target:
+                continue  # EXACT：目标日之外的行不参与判定（不回退旧值）
+            by_cell.setdefault(key, {}).setdefault(v.as_of.date(), set()).add(v.status)
+
+        missing_keys = want - set(by_cell)
+        probe: dict[tuple[tuple, str], ProbeCellStatus] = {}
+        if missing_keys:
+            probe = await self._query.probe_status(
+                tuple(sorted({i for i in identities}, key=lambda i: i.logical_key)),
+                tuple(sorted(set(instrument_ids))),
+                target_as_of=target,
+                dataset_revision=dataset_revision,
+            )
+
+        def _pick(statuses: set[FactorStatus] | frozenset[FactorStatus]) -> FactorCoverageState:
+            if FactorStatus.AVAILABLE in statuses:
+                return FactorCoverageState.PRESENT
+            if FactorStatus.UNAVAILABLE in statuses:
+                return FactorCoverageState.UNAVAILABLE
+            return FactorCoverageState.MISSING
+
+        cells: dict[tuple[tuple, str], CoverageState] = {}
+        for ident in identities:
+            for inst in instrument_ids:
+                key = (ident.logical_key, inst)
+                by_day = by_cell.get(key, {})
+                if by_day:
+                    value_day = max(by_day)
+                    statuses = by_day[value_day]
+                    cells[key] = CoverageState(
+                        state=_pick(statuses),
+                        value_as_of=value_day,
+                        stale=value_day < target,
+                    )
+                    continue
+                cell_probe = probe.get(key)
+                future = cell_probe.statuses if cell_probe is not None else set()
+                # R3 P1-4：probe 证据只来自目标业务日的同一批行——AVAILABLE
+                # 且未进快照 = 数据已写入但尚未到可见时间 → NOT_YET_PUBLISHED；
+                # 目标日行本身 MISSING/UNAVAILABLE → 如实保留；无行 → MISSING
+                published = FactorStatus.AVAILABLE in future or (
+                    FactorStatus.NOT_YET_PUBLISHED in future
+                )
+                if future and published:
+                    cells[key] = CoverageState(FactorCoverageState.NOT_YET_PUBLISHED)
+                elif future:
+                    # Store 中的数据本身就是 MISSING/UNAVAILABLE → 如实保留
+                    cells[key] = CoverageState(_pick(future))
+                else:
+                    cells[key] = CoverageState(FactorCoverageState.MISSING)
+        return FactorCoverageReport(cells=cells, target_as_of=target)

quant_core/app/factor/service/factor_selection_runner.py

@@ -0,0 +1,88 @@
+"""FactorSelectionRunner —— 历史时点选股编排。
+
+纯编排：IFactorQuery.get_snapshot → SelectionService.select。
+不生成 OrderIntent、不触碰 Portfolio/Execution——SelectionResult 由策略
+（或组装层适配器）显式翻译为 Signal。decision_time 即查询上界；
+identities = definition 的加权因子 + filter 因子。
+"""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from quant_core.app.factor.constants import FactorFreshness
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import FactorIdentity, FactorSnapshot
+from quant_core.app.factor.schema.selection_types import (
+    SelectionDefinition,
+    SelectionExposure,
+    SelectionResult,
+)
+from quant_core.app.factor.service.selection_service import SelectionService
+
+
+class FactorSelectionRunner:
+    def __init__(
+        self,
+        query: IFactorQuery,
+        selection: SelectionService | None = None,
+    ) -> None:
+        self._query = query
+        self._selection = selection or SelectionService()
+
+    async def select(
+        self,
+        definition: SelectionDefinition,
+        universe: tuple[str, ...] | list[str],
+        decision_time: datetime,
+        *,
+        target_as_of: date | None = None,
+        freshness: FactorFreshness = FactorFreshness.EXACT,
+        dataset_revision: str | None = None,
+        exposures: dict[str, SelectionExposure] | None = None,
+    ) -> SelectionResult:
+        return (
+            await self.run(
+                definition,
+                universe,
+                decision_time,
+                target_as_of=target_as_of,
+                freshness=freshness,
+                dataset_revision=dataset_revision,
+                exposures=exposures,
+            )
+        ).result
+
+    async def run(
+        self,
+        definition: SelectionDefinition,
+        universe: tuple[str, ...] | list[str],
+        decision_time: datetime,
+        *,
+        target_as_of: date | None = None,
+        freshness: FactorFreshness = FactorFreshness.EXACT,
+        dataset_revision: str | None = None,
+        exposures: dict[str, SelectionExposure] | None = None,
+    ) -> "FactorSelectionRun":
+        identities: list[FactorIdentity] = list(
+            dict.fromkeys(
+                [f.identity for f in definition.factors] + [f.identity for f in definition.filters]
+            )
+        )
+        snapshot = await self._query.get_snapshot(
+            identities,
+            list(universe),
+            decision_time,
+            target_as_of=target_as_of,
+            freshness=freshness,
+            dataset_revision=dataset_revision,
+        )
+        return FactorSelectionRun(
+            snapshot=snapshot,
+            result=self._selection.select(definition, universe, snapshot, exposures),
+        )
+
+
+@dataclass(frozen=True)
+class FactorSelectionRun:
+    snapshot: FactorSnapshot
+    result: SelectionResult

quant_core/app/factor/service/published_factor_execution_service.py

@@ -0,0 +1,160 @@
+"""已下载发布定义复用既有表达式/窗口/面板核心，不联网、不访问管理库。"""
+
+import json
+
+from quant_core.app.data.schema.adjustment_schema import AdjustmentType
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.factor.computation.factor_batch_evaluator import FactorBatchResult
+from quant_core.app.factor.computation.python_factor_executor import (
+    execute_python_panel,
+    execute_python_windows,
+)
+from quant_core.app.factor.interface.factor_local_data import FactorLocalData
+from quant_core.app.factor.schema.factor_input_schema import FactorInputRequest
+from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
+from quant_core.app.factor.schema.panel_policy import PANEL_UNITS
+from quant_core.app.factor.service.factor_input_service import prepare_research_panel
+from quant_core.app.factor.service.factor_local_execution_service import execute_local_factors
+from quant_core.common.local_run import content_digest
+
+
+async def execute_published_factors(
+    request: LocalFactorRequest, data: FactorLocalData
+) -> FactorBatchResult:
+    """静态定义在本地显式执行；记录完整输入证据并保留空值网格。"""
+    from quant_core.app.factor.computation.factor_source_loader import load_formulas
+
+    values, input_digests = {}, []
+    for publication in request.definitions:
+        spec = publication.definition.computation_spec
+        assert spec is not None
+        if spec.frequency.value != "1d":
+            raise ValueError("本地发布定义执行当前仅支持日线")
+        if spec.input_kind == "expression":
+            expressions = load_formulas(spec.python_source, spec.parameters)
+            if set(expressions) != {spec.name}:
+                raise ValueError("已发布表达式必须仅输出定义名称对应的因子")
+            expression = expressions[spec.name]
+            if expression.lookback > spec.lookback or set(expression.required_fields) - set(
+                spec.inputs
+            ):
+                raise ValueError("公式实际窗口/字段超出发布定义声明")
+            result = await execute_local_factors(
+                expressions,
+                data,
+                instrument_ids=request.instrument_ids,
+                start=request.start,
+                end=request.end,
+                view=request.view,
+                exclude_st=request.exclude_st,
+            )
+            values.update(result.values)
+            input_digests.append(result.input_digest)
+            continue
+        fields = tuple(name for name in spec.inputs if name in PANEL_UNITS)
+        if spec.input_kind == "window":
+            fields = tuple(name for name in PANEL_UNITS if name != "vwap")
+        if not fields or any(name not in PANEL_UNITS and name != "bar/1d" for name in spec.inputs):
+            raise ValueError("发布定义需要当前快照不支持的数据字段")
+        panel = await prepare_research_panel(
+            data,
+            FactorInputRequest(
+                instrument_ids=request.instrument_ids,
+                start=request.start,
+                end=request.end,
+                fields=fields,
+                lookback=spec.lookback,
+                view=request.view,
+                exclude_st=request.exclude_st,
+            ),
+        )
+        contract = spec.parameters.get("input_contract")
+        if contract is not None and contract != {
+            "universe_ref": panel.universe_ref,
+            "price_basis": panel.price_basis,
+            "units": panel.units,
+        }:
+            raise ValueError("面板股票池、价格口径或单位与发布定义不匹配")
+        input_digests.append(panel.input_digest)
+        if spec.input_kind == "panel":
+            computed = execute_python_panel(spec, panel)
+            if any(
+                not row.eligible and computed[(row.as_of, row.instrument_id)] is not None
+                for row in panel.rows
+            ):
+                raise ValueError("面板因子不能为不参与计算的标的返回非空值")
+        else:
+            computed = {}
+            for instrument in request.instrument_ids:
+                rows = sorted(
+                    (row for row in panel.rows if row.instrument_id == instrument),
+                    key=lambda row: row.as_of,
+                )
+                bars = await data.list_bars(
+                    instrument, "1d", rows[0].as_of, rows[-1].as_of, len(rows) + 1
+                )
+                if request.view.adjustment_type is not AdjustmentType.NONE:
+                    bars = (
+                        await data.get_adjusted_bars(
+                            instrument,
+                            "1d",
+                            request.view,
+                            rows[0].as_of,
+                            rows[-1].as_of,
+                            len(rows) + 1,
+                        )
+                    ).bars
+                previous_closes = {bar.timestamp: bar.previous_close for bar in bars}
+                input_digests.append(
+                    content_digest(
+                        json.dumps(
+                            [
+                                (ts.isoformat(), str(value) if value is not None else None)
+                                for ts, value in sorted(previous_closes.items())
+                            ]
+                        )
+                    )
+                )
+                calls, keys = [], []
+                for index, row in enumerate(rows):
+                    window = rows[max(0, index - spec.lookback + 1) : index + 1]
+                    key = (row.as_of, instrument)
+                    if len(window) < spec.lookback or any(
+                        not item.eligible
+                        or any(
+                            item.fields[name] is None
+                            for name in ("open", "high", "low", "close", "volume")
+                        )
+                        for item in window
+                    ):
+                        computed[key] = None
+                        continue
+                    window_bars = [
+                        BarResponse.model_validate(
+                            {
+                                "instrument_id": instrument,
+                                "timestamp": item.as_of,
+                                "frequency": "1d",
+                                "suspended": False,
+                                "previous_close": previous_closes.get(item.as_of),
+                                **item.fields,
+                            }
+                        )
+                        for item in window
+                    ]
+                    keys.append(key)
+                    calls.append((spec.python_source, window_bars, spec.parameters))
+                computed.update(zip(keys, execute_python_windows(calls), strict=True))
+        values[spec.name] = {
+            (ts, instrument): value
+            for (ts, instrument), value in computed.items()
+            if request.start <= ts.date() <= request.end
+        }
+    return FactorBatchResult(
+        values=values,
+        input_digest=content_digest(json.dumps(input_digests)),
+        definition_digest=content_digest(
+            json.dumps([item.content_digest for item in request.definitions])
+        ),
+        lookback=max(item.definition.lookback for item in request.definitions),
+    )