powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/research/adapter/market_label_query.py

@@ -0,0 +1,84 @@
+"""研究专用的未来收益标签读取，绝不注入 StrategyContext。"""
+
+import hashlib
+from datetime import datetime, time, timedelta
+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 AdjustmentType, BarViewRequest
+from quant_core.app.research.schema.dataset_schema import ResearchLabel, ResearchSampleRequest
+
+_CN = ZoneInfo("Asia/Shanghai")
+
+
+class MarketLabelQuery:
+    """以决策日收盘到 N 个交易日后收盘的后复权收益作标签。"""
+
+    def __init__(self, market: IMarketDataQuery) -> None:
+        self._market = market
+
+    async def forward_returns(
+        self, samples: tuple[ResearchSampleRequest, ...], horizon: int
+    ) -> tuple[ResearchLabel, ...]:
+        if horizon < 1:
+            raise ValueError("标签窗口必须为正整数")
+        if not samples:
+            return ()
+        first = min(item.decision_time.astimezone(_CN).date() for item in samples)
+        last = max(item.decision_time.astimezone(_CN).date() for item in samples)
+        calendar = await self._market.list_trading_days(
+            "XSHG", first, last + timedelta(days=horizon * 3 + 30)
+        )
+        days = sorted({row.trade_date for row in calendar if row.is_open})
+        ends = {}
+        for sample in samples:
+            day = sample.decision_time.astimezone(_CN).date()
+            if day not in days or days.index(day) + horizon >= len(days):
+                raise ValueError("交易日历不足以覆盖研究标签")
+            # 日收盘后的决策不得使用已经过去的入场价。
+            if sample.decision_time >= datetime.combine(day, time(15), tzinfo=_CN):
+                raise ValueError("该标签口径只适用于决策日收盘前的决策")
+            ends[sample.decision_time] = days[days.index(day) + horizon]
+        prices = {}
+        revisions = {}
+        for instrument in sorted(
+            {instrument for sample in samples for instrument in sample.universe}
+        ):
+            series = await self._market.get_adjusted_bars(
+                instrument,
+                "1d",
+                BarViewRequest(adjustment_type=AdjustmentType.POST),
+                datetime.combine(first, time.min, tzinfo=_CN),
+                datetime.combine(max(ends.values()), time.max, tzinfo=_CN),
+                100000,
+            )
+            if len(series.bars) >= 100000:
+                raise ValueError("标签行情达到查询上限，拒绝静默截断")
+            prices[instrument] = {
+                bar.timestamp.astimezone(_CN).date(): bar.close for bar in series.bars
+            }
+            revisions[instrument] = hashlib.sha256(series.model_dump_json().encode()).hexdigest()
+        labels = []
+        for sample in samples:
+            day = sample.decision_time.astimezone(_CN).date()
+            end = ends[sample.decision_time]
+            for instrument in sample.universe:
+                initial = prices[instrument].get(day)
+                final = prices[instrument].get(end)
+                value = (
+                    final / initial - Decimal(1)
+                    if initial is not None and final is not None and initial > 0
+                    else None
+                )
+                labels.append(
+                    ResearchLabel(
+                        sample.decision_time,
+                        instrument,
+                        datetime.combine(end, time(15), tzinfo=_CN),
+                        value,
+                        "post-adjusted-close-to-close",
+                        revisions[instrument],
+                    )
+                )
+        return tuple(labels)

quant_core/app/research/interface/research_dataset.py

@@ -0,0 +1,47 @@
+"""研究数据集输入和标签构造能力，禁止标签流入因子查询接口。"""
+
+from collections.abc import AsyncIterator
+from typing import Protocol
+
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+from quant_core.app.research.schema.dataset_schema import (
+    ResearchDataset,
+    ResearchLabel,
+    ResearchSampleRequest,
+)
+
+
+class IResearchLabelQuery(Protocol):
+    async def forward_returns(
+        self, samples: tuple[ResearchSampleRequest, ...], horizon: int
+    ) -> tuple[ResearchLabel, ...]: ...
+
+
+class IResearchDatasetBuilder(Protocol):
+    revisions: dict[str, str]
+
+    async def build(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        samples: tuple[ResearchSampleRequest, ...],
+        *,
+        factor_revision: str,
+        label_horizon: int | None = None,
+    ) -> ResearchDataset: ...
+
+    def iter_batches(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        samples: tuple[ResearchSampleRequest, ...],
+        *,
+        factor_revision: str,
+        batch_size: int = 32,
+        label_horizon: int | None = None,
+    ) -> AsyncIterator[ResearchDataset]:
+        """按决策时点分块读取，不在构建器内保留全部特征与标签。"""
+        ...
+
+
+class IResearchDatasetFactory(Protocol):
+    def __call__(self, factors: IFactorQuery) -> IResearchDatasetBuilder: ...

quant_core/app/research/interface/research_evaluation.py

@@ -0,0 +1,19 @@
+"""数据集评价接口，训练标签只进入评价端。"""
+
+from datetime import datetime
+from typing import Protocol
+
+from quant_core.app.factor.schema.diagnostic_types import FactorDiagnostics
+from quant_core.app.factor.schema.selection_types import SelectionDefinition, SelectionExposure
+from quant_core.app.research.schema.dataset_schema import ResearchDataset
+
+
+class IResearchEvaluation(Protocol):
+    def evaluate(
+        self,
+        dataset: ResearchDataset,
+        definition: SelectionDefinition,
+        *,
+        exposures: dict[datetime, dict[str, SelectionExposure]] | None = None,
+        quantiles: int = 5,
+    ) -> FactorDiagnostics: ...

quant_core/app/research/schema/comparison_schema.py

@@ -0,0 +1,12 @@
+"""参数实验比较投影，结果只引用已经持久化的运行证据。"""
+
+from pydantic import BaseModel, ConfigDict
+
+from quant_core.app.research.schema.research_schema import ResearchRunRecord
+
+
+class ResearchComparison(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    runs: tuple[ResearchRunRecord, ...]
+    comparable: bool
+    reasons: tuple[str, ...]

quant_core/app/research/schema/dataset_schema.py

@@ -0,0 +1,112 @@
+"""研究特征与前瞻标签分离；样本切分负责标签跨界清除。"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+
+from quant_core.app.factor.schema.factor_contract import FactorSnapshot
+
+
+@dataclass(frozen=True)
+class ResearchSampleRequest:
+    as_of: datetime
+    decision_time: datetime
+    universe: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if self.as_of.utcoffset() is None or self.decision_time.utcoffset() is None:
+            raise ValueError("研究时间必须带时区")
+        if self.as_of > self.decision_time or len(self.universe) != len(set(self.universe)):
+            raise ValueError("研究业务时点或股票池非法")
+
+
+@dataclass(frozen=True)
+class FeatureSlice:
+    request: ResearchSampleRequest
+    snapshot: FactorSnapshot
+
+    def __post_init__(self) -> None:
+        if self.snapshot.decision_time != self.request.decision_time:
+            raise ValueError("特征截面与样本决策时间不一致")
+        if any(row.as_of.date() != self.request.as_of.date() for row in self.snapshot.values):
+            raise ValueError("特征截面业务日期与请求不一致")
+        if any(row.instrument_id not in self.request.universe for row in self.snapshot.values):
+            raise ValueError("特征截面包含样本股票池之外的证券")
+
+
+@dataclass(frozen=True)
+class ResearchLabel:
+    decision_time: datetime
+    instrument_id: str
+    end_time: datetime
+    value: Decimal | None
+    price_basis: str
+    data_revision: str
+
+    def __post_init__(self) -> None:
+        if self.decision_time.utcoffset() is None or self.end_time.utcoffset() is None:
+            raise ValueError("标签时间必须带时区")
+        if self.end_time <= self.decision_time:
+            raise ValueError("前瞻标签终点必须晚于决策时间")
+        if self.value is not None and not self.value.is_finite():
+            raise ValueError("标签必须为有限值或缺值")
+
+
+@dataclass(frozen=True)
+class DatasetPartition:
+    name: str
+    start: datetime
+    end: datetime
+
+    def __post_init__(self) -> None:
+        if (
+            not self.name
+            or self.start.utcoffset() is None
+            or self.end.utcoffset() is None
+            or self.start >= self.end
+        ):
+            raise ValueError("研究分区需要名称及合法的带时区半开区间")
+
+
+@dataclass(frozen=True)
+class ResearchDataset:
+    """特征可交给共享评分器；标签只能交给研究评价器。"""
+
+    features: tuple[FeatureSlice, ...]
+    labels: tuple[ResearchLabel, ...] = ()
+
+    def __post_init__(self) -> None:
+        times = [item.request.decision_time for item in self.features]
+        if times != sorted(set(times)):
+            raise ValueError("研究特征必须按唯一决策时间排序")
+        valid = {
+            (item.request.decision_time, instrument)
+            for item in self.features
+            for instrument in item.request.universe
+        }
+        keys = [(label.decision_time, label.instrument_id) for label in self.labels]
+        if len(keys) != len(set(keys)) or set(keys) - valid:
+            raise ValueError("标签重复或不属于特征样本")
+
+    def split(self, partitions: tuple[DatasetPartition, ...]) -> dict[str, "ResearchDataset"]:
+        """半开时间分区；标签跨越分区末端时清除该证券的标签，保留特征。"""
+        ordered = sorted(partitions, key=lambda part: part.start)
+        if len({part.name for part in partitions}) != len(partitions):
+            raise ValueError("分区名称重复")
+        if any(left.end > right.start for left, right in zip(ordered, ordered[1:], strict=False)):
+            raise ValueError("训练/验证/测试分区不得重叠")
+        return {
+            part.name: ResearchDataset(
+                features=tuple(
+                    item
+                    for item in self.features
+                    if part.start <= item.request.decision_time < part.end
+                ),
+                labels=tuple(
+                    label
+                    for label in self.labels
+                    if part.start <= label.decision_time < part.end and label.end_time < part.end
+                ),
+            )
+            for part in partitions
+        }

quant_core/app/research/schema/research_schema.py

@@ -0,0 +1,120 @@
+"""可编辑研究与不可变运行证据的输入输出契约。"""
+
+import ast
+import hashlib
+from datetime import date
+from decimal import Decimal
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ResearchWorkspace(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    research_id: str = Field(pattern=r"^[a-z][a-z0-9_]*$", max_length=64)
+    name: str = Field(min_length=1, max_length=128)
+    description: str = ""
+    python_source: str = Field(min_length=1, max_length=65536)
+    default_parameters: dict[str, Any] = Field(default_factory=dict)
+
+    @property
+    def source_digest(self) -> str:
+        return hashlib.sha256(self.python_source.encode("utf-8")).hexdigest()
+
+    def validate_source(self) -> None:
+        module = ast.parse(self.python_source)
+        callbacks = [
+            node
+            for node in module.body
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == "run"
+        ]
+        if len(callbacks) != 1:
+            raise ValueError("研究源码必须定义唯一的 run(context, parameters)")
+        node = callbacks[0]
+        if (
+            len(node.args.posonlyargs) + len(node.args.args) != 2
+            or node.args.vararg is not None
+            or node.args.kwarg is not None
+            or node.args.kwonlyargs
+        ):
+            raise ValueError("run 回调必须声明 context、parameters 两个位置参数")
+        if len(self.python_source.encode("utf-8")) > 65536:
+            raise ValueError("研究源码超过 64 KiB")
+
+
+class ResearchMetric(BaseModel):
+    key: str
+    label: str
+    value: Decimal
+    unit: Literal["percent", "cny", "count", "ratio"]
+    explanation: str
+
+
+class ResearchEvidence(BaseModel):
+    """研究实验的可读摘要与可检查的逐样本证据。"""
+
+    question: str = Field(min_length=1)
+    conclusion: str = Field(min_length=1)
+    methodology: str = Field(min_length=1)
+    sample_start: date
+    sample_end: date
+    candidate_count: int = Field(ge=0)
+    observations: list[dict[str, Any]] = Field(default_factory=list)
+    exclusions: list[dict[str, Any]] = Field(default_factory=list)
+    metrics: list[ResearchMetric] = Field(default_factory=list)
+    limitations: list[str] = Field(min_length=1)
+    kind: Literal["event_study", "theoretical_scenario", "general"] = "general"
+
+    @model_validator(mode="after")
+    def check_samples(self) -> "ResearchEvidence":
+        if self.sample_start > self.sample_end:
+            raise ValueError("研究样本起点不得晚于终点")
+        if self.candidate_count != len(self.observations) + len(self.exclusions):
+            raise ValueError("候选数必须等于纳入数加排除数")
+        keys = [item.key for item in self.metrics]
+        if len(keys) != len(set(keys)):
+            raise ValueError("研究指标 key 不得重复")
+        return self
+
+
+class ResearchRunRequest(BaseModel):
+    research_id: str | None = None
+    python_source: str | None = None
+    start: date
+    end: date
+    parameters: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def check_source(self) -> "ResearchRunRequest":
+        if (self.research_id is None) == (self.python_source is None):
+            raise ValueError("research_id 与临时 python_source 必须且只能提供一个")
+        if self.start >= self.end:
+            raise ValueError("研究区间至少跨两个日期")
+        return self
+
+
+class ResearchRunRecord(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    uuid: str
+    status: Literal["completed", "failed"]
+    research_id: str | None
+    source_kind: Literal["workspace", "temporary"]
+    source_snapshot: str
+    source_digest: str
+    config_snapshot: dict[str, Any]
+    data_revisions: dict[str, str]
+    result: ResearchEvidence | None
+    error: str | None
+
+    @model_validator(mode="after")
+    def check_snapshot(self) -> "ResearchRunRecord":
+        digest = hashlib.sha256(self.source_snapshot.encode("utf-8")).hexdigest()
+        if digest != self.source_digest:
+            raise ValueError("研究运行源码摘要不匹配")
+        if (self.result is None) == (self.error is None):
+            raise ValueError("研究运行必须恰有结果或错误")
+        if (self.status == "completed") != (self.result is not None):
+            raise ValueError("研究运行状态与结果不一致")
+        return self

quant_core/app/research/service/research_dataset_service.py

@@ -0,0 +1,80 @@
+"""逐样本 PIT 特征装配；标签在独立步骤读取，不参与特征计算。"""
+
+from collections.abc import AsyncIterator
+
+from quant_core.app.factor.interface.public.factor_query import IFactorQuery
+from quant_core.app.factor.schema.factor_contract import FactorIdentity
+from quant_core.app.research.interface.research_dataset import IResearchLabelQuery
+from quant_core.app.research.schema.dataset_schema import (
+    FeatureSlice,
+    ResearchDataset,
+    ResearchSampleRequest,
+)
+
+
+class ResearchDatasetService:
+    """固定因子修订与完整身份，每个决策时间只查询一次完整截面。"""
+
+    def __init__(self, factors: IFactorQuery, labels: IResearchLabelQuery) -> None:
+        self._factors = factors
+        self._labels = labels
+        self.revisions: dict[str, str] = {}
+
+    async def build(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        samples: tuple[ResearchSampleRequest, ...],
+        *,
+        factor_revision: str,
+        label_horizon: int | None = None,
+    ) -> ResearchDataset:
+        if not identities or len(set(identities)) != len(identities) or not factor_revision:
+            raise ValueError("数据集必须指定唯一完整因子身份和固定修订")
+        if label_horizon is not None and label_horizon < 1:
+            raise ValueError("标签窗口必须为正整数")
+        self.revisions["dataset_factor"] = factor_revision
+        features = []
+        for sample in sorted(samples, key=lambda item: item.decision_time):
+            snapshot = await self._factors.get_snapshot(
+                list(identities),
+                list(sample.universe),
+                sample.decision_time,
+                target_as_of=sample.as_of.date(),
+                dataset_revision=factor_revision,
+            )
+            if any(row.identity not in identities for row in snapshot.values):
+                raise ValueError("查询返回非请求身份")
+            features.append(FeatureSlice(sample, snapshot))
+        # 先验证特征时间键，避免无效样本触发昂贵的前瞻读取。
+        dataset = ResearchDataset(tuple(features))
+        if label_horizon is None:
+            return dataset
+        labels = await self._labels.forward_returns(samples, label_horizon)
+        for label in labels:
+            self.revisions[f"label:{label.instrument_id}:{label.end_time.isoformat()}"] = (
+                label.data_revision
+            )
+        return ResearchDataset(dataset.features, labels)
+
+    async def iter_batches(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        samples: tuple[ResearchSampleRequest, ...],
+        *,
+        factor_revision: str,
+        batch_size: int = 32,
+        label_horizon: int | None = None,
+    ) -> AsyncIterator[ResearchDataset]:
+        """复用统一构建路径；跨分块标签按真实远期窗口读取，不在分块边缘截断。"""
+        if batch_size < 1:
+            raise ValueError("研究数据分块大小必须为正整数")
+        ordered = tuple(sorted(samples, key=lambda sample: sample.decision_time))
+        if len({sample.decision_time for sample in ordered}) != len(ordered):
+            raise ValueError("研究特征必须按唯一决策时间排序")
+        for start in range(0, len(ordered), batch_size):
+            yield await self.build(
+                identities,
+                ordered[start : start + batch_size],
+                factor_revision=factor_revision,
+                label_horizon=label_horizon,
+            )

quant_core/app/research/service/research_evaluation_service.py

@@ -0,0 +1,56 @@
+"""共享因子评分后的 IC、分层与换手评价，不另写一套评分。"""
+
+from datetime import datetime
+
+from quant_core.app.factor.interface.public.factor_diagnostics import IFactorDiagnostics
+from quant_core.app.factor.interface.public.factor_selection import IFactorSelection
+from quant_core.app.factor.schema.diagnostic_types import CrossSection, FactorDiagnostics
+from quant_core.app.factor.schema.selection_types import SelectionDefinition, SelectionExposure
+from quant_core.app.research.schema.dataset_schema import ResearchDataset
+
+
+class ResearchEvaluationService:
+    def __init__(self, selection: IFactorSelection, diagnostics: IFactorDiagnostics) -> None:
+        self._selection = selection
+        self._diagnostics = diagnostics
+
+    def evaluate(
+        self,
+        dataset: ResearchDataset,
+        definition: SelectionDefinition,
+        *,
+        exposures: dict[datetime, dict[str, SelectionExposure]] | None = None,
+        quantiles: int = 5,
+    ) -> FactorDiagnostics:
+        """全截面评分进入诊断，TopN 仅用于选股换手，不截断 IC 样本。"""
+        sections = []
+        selections = []
+        labels = {
+            (label.decision_time, label.instrument_id): label.value for label in dataset.labels
+        }
+        for feature in dataset.features:
+            timestamp = feature.request.decision_time
+            result = self._selection.select(
+                definition,
+                feature.request.universe,
+                feature.snapshot,
+                (exposures or {}).get(timestamp),
+            )
+            scores = {item.instrument_id: item.score for item in result.selected}
+            scores.update(
+                {
+                    item.instrument_id: item.score
+                    for item in result.excluded
+                    if item.reason == "top_n" and item.score is not None
+                }
+            )
+            returns = {
+                instrument: value
+                for instrument in feature.request.universe
+                if (value := labels.get((timestamp, instrument))) is not None
+            }
+            sections.append(CrossSection(timestamp.date(), scores, returns))
+            selections.append(tuple(item.instrument_id for item in result.selected))
+        return self._diagnostics.analyze(
+            tuple(sections), quantiles=quantiles, selections=tuple(selections)
+        )