powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/factor/service/factor_input_service.py

@@ -0,0 +1,258 @@
+"""由可信本地事实构造交易日网格；复权、缺口与参与范围均进入输入证据。"""
+
+import hashlib
+import json
+from bisect import bisect_left
+from datetime import date, datetime, time
+from decimal import Decimal
+from zoneinfo import ZoneInfo
+
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.data.schema.adjustment_schema import (
+    AdjustedBarResponse,
+    AdjustmentAnchorMode,
+    AdjustmentType,
+)
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.data.service.calendar_coverage_service import build_calendar_coverage
+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.factor_panel import FactorPanel, FactorPanelRow
+from quant_core.app.factor.schema.panel_policy import PANEL_UNITS, PRICE_BASIS, listed_roster_ref
+
+_CN = ZoneInfo("Asia/Shanghai")
+_EXCHANGES = {"XSHG", "XSHE", "BJSE"}
+
+
+async def prepare_research_panel(data: FactorLocalData, request: FactorInputRequest) -> FactorPanel:
+    """返回包含预热日的矩形面板；上市前、退市后及停牌不参与横截面。"""
+    if set(request.fields) - PANEL_UNITS.keys():
+        raise ValueError("当前输入准备仅支持量价字段")
+    lower = data.start.astimezone(_CN).date()
+    upper = data.end.astimezone(_CN).date()
+    if request.start < lower or request.end > upper:
+        raise ValueError("输出范围超出本地快照，请先准备所需数据")
+    instruments = [await data.get_instrument(key) for key in sorted(request.instrument_ids)]
+    if any(row.listed_date is None for row in instruments):
+        raise ValueError("参与池缺少可信上市日期，不能推断历史成员")
+    exchanges = {row.exchange for row in instruments}
+    if not exchanges.issubset(_EXCHANGES):
+        raise ValueError("首批日线准备仅支持 A 股交易所")
+    calendars = []
+    for exchange in sorted(exchanges):
+        rows = await data.list_calendar_days(exchange, lower, request.end)
+        if any(
+            row.exchange != exchange or not lower <= row.trade_date <= request.end for row in rows
+        ):
+            raise ValueError("交易日历返回了不属于请求范围的事实")
+        if len({row.trade_date for row in rows}) != len(rows):
+            raise ValueError("交易日历包含重复日期")
+        coverage = build_calendar_coverage(exchange, lower, request.end, rows)
+        if coverage.missing_days:
+            raise ValueError("本地交易日历不完整，不能推断预热范围")
+        calendars.append(coverage.open_days)
+    if any(days != calendars[0] for days in calendars[1:]):
+        raise ValueError("参与交易所的交易日轴不同，需要独立会话准备")
+    days = calendars[0]
+    first = bisect_left(days, request.start)
+    if first >= len(days):
+        raise ValueError("请求区间没有交易日")
+    warmup = first - request.lookback + 1
+    if warmup < 0:
+        raise ValueError(f"本地快照缺少预热交易日，需要至少 {request.lookback} 期")
+    calendar = tuple(datetime.combine(day, time(15), _CN) for day in days[warmup:])
+    if calendar[0] < data.start or calendar[-1] > data.end:
+        raise ValueError("快照未覆盖完整交易日收盘时间")
+    view = request.view
+    if view.known_at is not None:
+        raise ValueError("当前行情快照不支持历史知识时间查询")
+    if view.adjustment_type is AdjustmentType.PRE:
+        if view.anchor_mode is not AdjustmentAnchorMode.FIXED_DATE:
+            raise ValueError("批量面板前复权必须显式使用固定日期锚点")
+        if view.anchor_date is None or not lower <= view.anchor_date <= upper:
+            raise ValueError("复权锚点超出本地事实范围")
+    rows = []
+    revisions = []
+    membership = []
+    for instrument in instruments:
+        assert instrument.listed_date is not None
+        raw = await data.list_bars(
+            instrument.instrument_id, "1d", calendar[0], calendar[-1], len(calendar) + 1
+        )
+        if len(raw) > len(calendar):
+            raise ValueError("本地日线包含重复或额外时间点")
+        values = raw
+        if raw and view.adjustment_type is not AdjustmentType.NONE:
+            adjusted = await data.get_adjusted_bars(
+                instrument.instrument_id,
+                "1d",
+                view,
+                calendar[0],
+                calendar[-1],
+                len(calendar) + 1,
+            )
+            values = adjusted.bars
+            revisions.append(
+                (instrument.instrument_id, adjusted.factor_revision, str(adjusted.anchor_date))
+            )
+        by_time = {bar.timestamp: bar for bar in values}
+        if any(
+            bar.instrument_id != instrument.instrument_id or bar.frequency != "1d" for bar in values
+        ):
+            raise ValueError("行情包含其他证券或频率")
+        if len(by_time) != len(values) or set(by_time) - set(calendar):
+            raise ValueError("日线时间与交易日历不一致")
+        membership.append(
+            (
+                instrument.instrument_id,
+                str(instrument.listed_date),
+                str(instrument.delisted_date),
+            )
+        )
+        status = {
+            f.trade_date: f
+            for f in await data.list_daily_facts(
+                instrument.instrument_id, calendar[0].date(), calendar[-1].date()
+            )
+        }
+        for timestamp in calendar:
+            listed = instrument.listed_date <= timestamp.date() and (
+                instrument.delisted_date is None or timestamp.date() <= instrument.delisted_date
+            )
+            bar = by_time.get(timestamp)
+            fact = status.get(timestamp.date())
+            full_day_halt = fact is not None and fact.suspension_status == "full_day"
+            if listed and bar is None and not full_day_halt and request.missing_policy == "error":
+                raise ValueError(f"行情缺口: {instrument.instrument_id} {timestamp.date()}")
+            eligible = listed and bar is not None and not bar.suspended and not full_day_halt
+            if request.exclude_st and listed:
+                fact = status.get(timestamp.date())
+                if fact is None or fact.special_type is None:
+                    raise ValueError(
+                        f"历史 ST 状态未知: {instrument.instrument_id} {timestamp.date()}"
+                    )
+                eligible = eligible and fact.special_type == "Normal"
+            fields: dict[str, Decimal | None] = dict.fromkeys(request.fields)
+            if eligible:
+                assert bar is not None
+                fields = _bar_fields(bar, request.fields)
+            if (
+                eligible
+                and request.missing_policy == "error"
+                and any(value is None for value in fields.values())
+            ):
+                raise ValueError(f"输入字段缺失: {instrument.instrument_id} {timestamp.date()}")
+            rows.append(
+                FactorPanelRow(
+                    instrument_id=instrument.instrument_id,
+                    as_of=timestamp,
+                    available_at=data.end,
+                    eligible=eligible,
+                    fields=fields,
+                )
+            )
+    return FactorPanel(
+        decision_time=data.end,
+        price_basis=view.model_dump_json(),
+        universe_ref=listed_roster_ref(request.instrument_ids),
+        universe_revision=hashlib.sha256(json.dumps(membership).encode()).hexdigest(),
+        market_revision=hashlib.sha256(json.dumps([data.revision, revisions]).encode()).hexdigest(),
+        units={field: PANEL_UNITS[field] for field in request.fields},
+        rows=tuple(rows),
+    )
+
+
+async def prepare_decision_panel(
+    market: IMarketDataQuery,
+    instrument_ids: tuple[str, ...],
+    day: date,
+    next_day: date,
+    lookback: int,
+) -> FactorPanel:
+    """只做输入准备，不计算因子或发布结果；未知上市时间拒绝猜测。"""
+    if next_day <= day or lookback < 1 or not instrument_ids:
+        raise ValueError("面板窗口参数非法")
+    if len(set(instrument_ids)) != len(instrument_ids):
+        raise ValueError("面板候选证券不得重复")
+    decision_time = datetime.combine(next_day, time(9, 30), tzinfo=_CN)
+    as_of = datetime.combine(day, time(15), tzinfo=_CN)
+    rows: list[FactorPanelRow] = []
+    market_evidence = []
+    universe_evidence = []
+    for instrument_id in sorted(instrument_ids):
+        instrument = await market.get_instrument(instrument_id)
+        if instrument.listed_date is None:
+            raise ValueError(f"缺少可信上市日期: {instrument_id}")
+        universe_evidence.append(
+            (instrument_id, str(instrument.listed_date), str(instrument.delisted_date))
+        )
+        if day < instrument.listed_date:
+            rows.append(
+                FactorPanelRow(
+                    instrument_id=instrument_id,
+                    as_of=as_of,
+                    available_at=decision_time,
+                    eligible=False,
+                    fields=dict.fromkeys(PANEL_UNITS),
+                )
+            )
+            market_evidence.append((instrument_id, "before_listing"))
+            continue
+        windows = await market.get_pit_daily_windows(instrument_id, [day], [next_day], lookback)
+        if len(windows) != 1 or windows[0].as_of != day or windows[0].anchor_date != next_day:
+            raise ValueError("Market 返回的面板窗口与请求不一致")
+        window = windows[0]
+        market_evidence.append((instrument_id, window.input_digest))
+        for bar in window.bars:
+            timestamp = bar.timestamp.astimezone(_CN)
+            if timestamp.date() > day or bar.instrument_id != instrument_id:
+                raise ValueError("Market 返回越界行情")
+            eligible = instrument.listed_date <= timestamp.date() and (
+                instrument.delisted_date is None or timestamp.date() <= instrument.delisted_date
+            )
+            fields = _bar_fields(bar, tuple(PANEL_UNITS))
+            rows.append(
+                FactorPanelRow(
+                    instrument_id=instrument_id,
+                    as_of=datetime.combine(timestamp.date(), time(15), tzinfo=_CN),
+                    # 使用本次窗口的可见时点，避免将决策日复权锚点伪装成历史已知。
+                    available_at=decision_time,
+                    eligible=eligible,
+                    fields=fields,
+                )
+            )
+        if not window.bars or window.bars[-1].timestamp.astimezone(_CN).date() != day:
+            rows.append(
+                FactorPanelRow(
+                    instrument_id=instrument_id,
+                    as_of=as_of,
+                    available_at=decision_time,
+                    eligible=False,
+                    fields=dict.fromkeys(PANEL_UNITS),
+                )
+            )
+    return FactorPanel(
+        decision_time=decision_time,
+        price_basis=PRICE_BASIS,
+        universe_ref=listed_roster_ref(instrument_ids),
+        universe_revision=hashlib.sha256(json.dumps(universe_evidence).encode()).hexdigest(),
+        market_revision=hashlib.sha256(json.dumps(market_evidence).encode()).hexdigest(),
+        units=PANEL_UNITS,
+        rows=tuple(rows),
+    )
+
+
+def _bar_fields(
+    bar: BarResponse | AdjustedBarResponse, names: tuple[str, ...]
+) -> dict[str, Decimal | None]:
+    """统一价格字段与 VWAP 转换；是否参与计算由各时点政策决定。"""
+    fields: dict[str, Decimal | None] = {}
+    for name in names:
+        if name == "vwap":
+            fields[name] = (
+                bar.amount / bar.volume if bar.amount is not None and bar.volume > 0 else None
+            )
+        else:
+            value = getattr(bar, name)
+            fields[name] = Decimal(value) if value is not None else None
+    return fields

quant_core/app/factor/service/factor_local_execution_service.py

@@ -0,0 +1,51 @@
+"""PQFactor 本地入口：显式快照、交易时间轴与历史参与池，计算不联网。"""
+
+from datetime import date, datetime, time
+from zoneinfo import ZoneInfo
+
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+from quant_core.app.factor.computation.factor_batch_evaluator import (
+    FactorBatchResult,
+    execute_factors,
+)
+from quant_core.app.factor.computation.factor_expression import FactorExpression
+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.service.factor_input_service import prepare_research_panel
+
+
+async def execute_local_factors(
+    factors: dict[str, FactorExpression],
+    data: FactorLocalData,
+    *,
+    instrument_ids: tuple[str, ...],
+    start: date,
+    end: date,
+    view: BarViewRequest,
+    exclude_st: bool = False,
+    output_instruments: tuple[str, ...] | None = None,
+) -> FactorBatchResult:
+    """从已加载快照自动准备公式输入；复用 data 可避免重复读盘，不联网。"""
+    if not factors:
+        raise ValueError("必须提供至少一个公式")
+    fields = sorted(set().union(*(factor.required_fields for factor in factors.values())))
+    if not fields:
+        raise ValueError("公式必须引用至少一个输入字段")
+    request = FactorInputRequest(
+        instrument_ids=instrument_ids,
+        start=start,
+        end=end,
+        fields=tuple(fields),
+        lookback=max(factor.lookback for factor in factors.values()),
+        view=view,
+        exclude_st=exclude_st,
+    )
+    panel = await prepare_research_panel(data, request)
+    cn = ZoneInfo("Asia/Shanghai")
+    return execute_factors(
+        factors,
+        panel,
+        start=datetime.combine(start, time.min, cn),
+        end=datetime.combine(end, time.max, cn),
+        output_instruments=output_instruments,
+    )

quant_core/app/factor/service/factor_panel_service.py

@@ -0,0 +1,86 @@
+"""面板试算与 Canonical 输出装配；不隐式发布任何研究试算。"""
+
+import asyncio
+from collections import Counter
+from datetime import datetime
+
+from quant_core.app.factor.constants import LOCAL_FACTOR_SOURCE, FactorSourceKind, FactorStatus
+from quant_core.app.factor.interface.factor_execution import PanelExecutor
+from quant_core.app.factor.schema.factor_contract import (
+    FactorDefinition,
+    FactorProvenance,
+    FactorValue,
+)
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+
+
+class FactorPanelService:
+    """依赖计算接口，发布与持久化交给现有 Factor 修订流程。"""
+
+    def __init__(self, runner: PanelExecutor) -> None:
+        self._runner = runner
+
+    async def compute(
+        self,
+        definitions: list[FactorDefinition],
+        panel: FactorPanel,
+        *,
+        as_of: datetime,
+        dataset_revision: str,
+    ) -> list[FactorValue]:
+        """只输出目标业务时点；所有输入在此次决策时间已经合法可见。"""
+        panel = FactorPanel.model_validate(panel.model_dump())
+        if as_of.utcoffset() is None or as_of > panel.decision_time:
+            raise ValueError("面板输出时点非法")
+        if any(row.as_of > as_of for row in panel.rows):
+            raise ValueError("面板不得包含输出业务时点之后的输入")
+        if len({item.identity for item in definitions}) != len(definitions):
+            raise ValueError("重复完整因子身份")
+        output_rows = tuple(row for row in panel.rows if row.as_of == as_of)
+        history_counts = Counter(row.instrument_id for row in panel.rows)
+        input_digest = panel.input_digest
+        result = []
+        for definition in definitions:
+            spec = definition.computation_spec
+            if (
+                spec is None
+                or spec.input_kind != "panel"
+                or definition.identity.source != LOCAL_FACTOR_SOURCE
+            ):
+                raise ValueError("必须使用本地面板定义")
+            contract = spec.parameters.get("input_contract")
+            actual = {
+                "universe_ref": panel.universe_ref,
+                "price_basis": panel.price_basis,
+                "units": panel.units,
+            }
+            if contract != actual:
+                raise ValueError("面板股票池政策、单位或价格口径与定义不一致")
+            values = await asyncio.to_thread(self._runner, spec, panel)
+            for row in output_rows:
+                sufficient = history_counts[row.instrument_id] >= spec.lookback
+                value = (
+                    values[(row.as_of, row.instrument_id)] if row.eligible and sufficient else None
+                )
+                result.append(
+                    FactorValue(
+                        identity=definition.identity,
+                        instrument_id=row.instrument_id,
+                        as_of=as_of,
+                        available_at=panel.decision_time,
+                        value=value,
+                        status=FactorStatus.AVAILABLE
+                        if value is not None
+                        else FactorStatus.MISSING,
+                        provenance=FactorProvenance(
+                            source_kind=FactorSourceKind.LOCAL_CALCULATOR,
+                            provider_id=LOCAL_FACTOR_SOURCE,
+                            retrieval_ref="python:compute_panel",
+                            content_digest=spec.content_digest,
+                            dataset_revision=dataset_revision,
+                            provider_revision=panel.market_revision,
+                            note=f"input_sha256={input_digest};universe_revision={panel.universe_revision}",
+                        ),
+                    )
+                )
+        return result