powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/factor/computation/universe_filter.py

@@ -0,0 +1,25 @@
+"""横截面算子的历史入池门禁；ContextVar 隔离并发计算。"""
+
+from contextvars import ContextVar
+from datetime import datetime
+
+import polars as pl
+
+from quant_core.app.factor.computation.panel_expression import PanelExpression
+
+ELIGIBLE_KEYS: ContextVar[frozenset[tuple[datetime, str]] | None] = ContextVar(
+    "alpha_eligible_keys", default=None
+)
+
+
+def mask_cross_section(feature: PanelExpression) -> PanelExpression:
+    """仅横截面聚合前掩码，避免删除未入池证券的时序历史。"""
+    keys = ELIGIBLE_KEYS.get()
+    if keys is None:
+        return feature
+    mask = pl.Series(
+        [key in keys for key in feature.df.select("datetime", "vt_symbol").iter_rows()]
+    )
+    return PanelExpression(
+        feature.df.with_columns(pl.when(mask).then(pl.col("data")).otherwise(None).alias("data"))
+    )

quant_core/app/factor/constants.py

@@ -0,0 +1,114 @@
+"""Factor Domain 常量与枚举（T1 Canonical Contract）"""
+
+from enum import Enum
+
+# dataset_revision 兜底值：契约侧未声明 dataset_revision 的行（遗留数据 /
+# 逐次本地计算）入库时归一为该值——Store 列 NOT NULL，唯一键含 dataset_revision
+# （R2-2：NULL 在 PG 唯一约束下互不冲突，必须归一才能保证修订行不串键）。
+LEGACY_DATASET_REVISION = "0-legacy"
+
+# 本地逐次计算的 dataset_revision（local-python 身份专用；与批量同步的
+# 时间戳批次修订空间不重叠——同一身份内才比较修订序）
+LOCAL_DATASET_REVISION = "local"
+LOCAL_FACTOR_SOURCE = "local-python"
+
+FACTOR_MOMENTUM_20D = "momentum_20d"
+FACTOR_VOLUME_RATIO_5D = "volume_ratio_5d"
+FACTOR_MA_CLOSE_10 = "ma_close_10"
+
+
+class FactorDefinitionStatus(str, Enum):
+    """因子定义生命周期；与因子值可用性 FactorStatus 分离。"""
+
+    DRAFT = "draft"
+    VALIDATING = "validating"
+    VALIDATED = "validated"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    DEPRECATED = "deprecated"
+
+
+class FactorSourceType(str, Enum):
+    """因子输入来源类别。"""
+
+    MARKET = "market"
+    FUNDAMENTAL = "fundamental"
+    FLOW = "flow"
+    ALTERNATIVE = "alternative"
+    DERIVED = "derived"
+
+
+class FactorDataModality(str, Enum):
+    """因子输入模态。"""
+
+    STRUCTURED = "structured"
+    TEXT = "text"
+    IMAGE = "image"
+    MULTIMODAL = "multimodal"
+
+
+class FactorAuthoringSource(str, Enum):
+    """因子规格的创建入口。"""
+
+    HUMAN = "human"
+    AGENT = "agent"
+    PYTHON = "python"
+
+
+class FactorSourceKind(str, Enum):
+    """因子值的三类生产来源（AC-1：共享同一 Canonical Contract）"""
+
+    EXTERNAL_PROVIDER = "external_provider"
+    LOCAL_CALCULATOR = "local_calculator"
+    MODEL = "model"
+
+
+class FactorStatus(str, Enum):
+    """因子值状态（缺失/不可用/未发布禁止用 0 表达——NULL ≠ 0）"""
+
+    AVAILABLE = "available"
+    MISSING = "missing"
+    UNAVAILABLE = "unavailable"
+    NOT_YET_PUBLISHED = "not_yet_published"
+
+
+class FactorFrequency(str, Enum):
+    """因子结果的时间粒度；分钟计算流程尚未实现。"""
+
+    DAILY = "1d"
+    MINUTE_1 = "1m"
+    MINUTE_5 = "5m"
+
+
+class FactorCoverageState(str, Enum):
+    """截面覆盖状态（R1-4：封闭枚举，逐 identity×instrument 格）
+
+    - PRESENT：decision_time 可见且存在可消费值行；
+    - MISSING：该格无可见值行（含 Provider 明示缺失）——不是 present，更不是 0；
+    - UNAVAILABLE：Provider 明示不可用（区别于未知缺失）；
+    - NOT_YET_PUBLISHED：Store 中存在该格数据但 available_at > decision_time
+      （尚未到可见时间；区别于 MISSING）。
+
+    「历史窗口不足（insufficient_history）」需要 lookback 输入才能判定，
+    归 Selection/策略层语义（T5），不在本报告封闭枚举内预建空壳。
+    """
+
+    PRESENT = "present"
+    MISSING = "missing"
+    UNAVAILABLE = "unavailable"
+    NOT_YET_PUBLISHED = "not_yet_published"
+
+
+class FactorFreshness(str, Enum):
+    """截面新鲜度策略（R2-5，T5 前裁定：默认精确、回退须显式）
+
+    - EXACT：只消费 target_as_of 当日的值；目标日无值 → MISSING/
+      NOT_YET_PUBLISHED，绝不因历史上存在旧值就冒充 PRESENT（默认，
+      语义最诚实、无静默过期风险）；
+    - LATEST_KNOWN：目标日无值时显式回退到目标日之前最近的可得历史值，
+      覆盖报告中以 stale 标注 + value_as_of 暴露实际归属日——回退必须
+      是策略作者的显式选择，不是 Runtime 默认行为。
+    """
+
+    EXACT = "exact"
+    LATEST_KNOWN = "latest_known"

quant_core/app/factor/exceptions.py

@@ -0,0 +1,35 @@
+"""Factor 错误类型。"""
+
+from quant_core.common.exceptions.base import AppException
+
+
+class FactorPublicationError(AppException):
+    """因子发布内容或摘要不符合契约。"""
+
+    error_code = "FACTOR_PUBLICATION_ERROR"
+    http_status = 422
+
+
+class PublishedFactorNotFound(AppException):
+    """指定发布版本不存在。"""
+
+    error_code = "PUBLISHED_FACTOR_NOT_FOUND"
+    http_status = 404
+
+
+class FactorNotRegisteredException(AppException):
+    """引用未注册因子。"""
+
+    error_code = "FACTOR_NOT_REGISTERED"
+    http_status = 409
+
+    def __init__(self, factor_name: str):
+        super().__init__(f"factor 未注册: {factor_name}")
+
+
+class InsufficientFactorHistoryError(ValueError):
+    """交易日历不足以解析 lookback/warmup 窗口"""
+
+
+class InvalidFactorRangeError(ValueError):
+    """非法查询区间（如 start > end）"""

quant_core/app/factor/factor_dependency.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from functools import partial
+
+"""Factor 的框架无关依赖组装；入口不直接构造 Adapter/Repository。"""
+
+from datetime import date
+
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.factor.computation.python_factor_executor import (
+    execute_python_windows,
+)
+from quant_core.app.factor.interface.public.factor_diagnostics import IFactorDiagnostics
+from quant_core.app.factor.interface.public.factor_exposure_query import IFactorExposureQuery
+from quant_core.app.factor.interface.public.factor_selection import IFactorSelection
+from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
+from quant_core.app.factor.schema.factor_contract import FactorDefinition
+from quant_core.app.factor.service.factor_compute_service import FactorComputeService
+from quant_core.app.factor.service.selection_service import SelectionService
+
+
+def build_factor_compute(
+    trading_days: list[date], definitions: list[FactorDefinition]
+) -> FactorComputeService:
+    """只按数据库读取的定义组装计算器，不注册代码内置因子。"""
+    return FactorComputeService(trading_days, definitions, execute_python_windows)
+
+
+def build_factor_selection() -> IFactorSelection:
+    """向其他模块提供唯一的因子横截面评分实现。"""
+    return SelectionService()
+
+
+def builtin_factor_specs(
+    family: str,
+    *,
+    universe_ref: str,
+    price_basis: str,
+    units: dict[str, str],
+    instrument_ids: tuple[str, ...] = (),
+) -> list[FactorComputationSpec]:
+    """读取内置候选配方，不产生数据库副作用。"""
+    from quant_core.app.factor.builtin.factor_recipe_catalog import recipe_specs
+
+    return recipe_specs(
+        family,
+        universe_ref=universe_ref,
+        price_basis=price_basis,
+        units=units,
+        instrument_ids=instrument_ids,
+    )
+
+
+def build_factor_diagnostics() -> IFactorDiagnostics:
+    """诊断数学由 Factor 维护，研究仅通过公开能力调用。"""
+    from quant_core.app.factor.service.factor_diagnostics_service import FactorDiagnosticsService
+
+    return FactorDiagnosticsService()
+
+
+def build_factor_exposure_query(market: IMarketDataQuery) -> IFactorExposureQuery:
+    """跨域绑定市场依赖，策略仅接收暴露查询协议。"""
+    from quant_core.app.factor.service.factor_exposure_service import query_exposures
+
+    return partial(query_exposures, market)

quant_core/app/factor/interface/factor_compute.py

@@ -0,0 +1,12 @@
+"""物化流程依赖的因子计算接口。"""
+
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_compute_request import FactorComputeRequest
+from quant_core.app.factor.schema.factor_contract import FactorValue
+
+
+class IFactorCompute(Protocol):
+    async def compute_many(
+        self, requests: list[FactorComputeRequest], *, dataset_revision: str
+    ) -> list[FactorValue]: ...

quant_core/app/factor/interface/factor_execution.py

@@ -0,0 +1,15 @@
+"""可替换 Python 执行函数的类型契约。"""
+
+from collections.abc import Callable
+from decimal import Decimal
+from typing import Any
+
+from quant_core.app.data.schema.market_schema import BarResponse
+from quant_core.app.factor.schema.factor_computation_schema import FactorComputationSpec
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+from quant_core.app.factor.schema.factor_result_schema import PanelValues
+
+WindowExecutor = Callable[
+    [list[tuple[str, list[BarResponse], dict[str, Any]]]], list[Decimal | None]
+]
+PanelExecutor = Callable[[FactorComputationSpec, FactorPanel], PanelValues]

quant_core/app/factor/interface/factor_local_data.py

@@ -0,0 +1,42 @@
+"""因子输入准备消费的本地快照接口，不包含网络同步能力。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.adjustment_schema import AdjustedBarSeries, BarViewRequest
+from quant_core.app.data.schema.history_schema import DailyFactResponse
+from quant_core.app.data.schema.market_schema import (
+    BarResponse,
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+)
+
+
+class FactorLocalData(Protocol):
+    start: datetime
+    end: datetime
+    revision: str
+
+    async def list_daily_facts(
+        self, instrument_id: str, start: date, end: date
+    ) -> list[DailyFactResponse]: ...
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse: ...
+
+    async def list_calendar_days(
+        self, exchange: str, start: date, end: date, only_open: bool = False
+    ) -> list[TradingCalendarDayResponse]: ...
+
+    async def list_bars(
+        self, instrument_id: str, frequency: str, start: datetime, end: datetime, limit: int
+    ) -> list[BarResponse]: ...
+
+    async def get_adjusted_bars(
+        self,
+        instrument_id: str,
+        frequency: str,
+        view: BarViewRequest,
+        start: datetime,
+        end: datetime,
+        limit: int,
+    ) -> AdjustedBarSeries: ...

quant_core/app/factor/interface/factor_panel_compute.py

@@ -0,0 +1,18 @@
+"""面板物化对计算服务的依赖契约。"""
+
+from datetime import datetime
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_contract import FactorDefinition, FactorValue
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+
+
+class IFactorPanelCompute(Protocol):
+    async def compute(
+        self,
+        definitions: list[FactorDefinition],
+        panel: FactorPanel,
+        *,
+        as_of: datetime,
+        dataset_revision: str,
+    ) -> list[FactorValue]: ...

quant_core/app/factor/interface/factor_panel_input.py

@@ -0,0 +1,12 @@
+"""计算核心所需的 PIT 面板准备接口；数据供应方可替换。"""
+
+from datetime import date
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_panel import FactorPanel
+
+
+class IFactorPanelInput(Protocol):
+    async def __call__(
+        self, instrument_ids: tuple[str, ...], day: date, next_day: date, lookback: int
+    ) -> FactorPanel: ...

quant_core/app/factor/interface/factor_query_store.py

@@ -0,0 +1,39 @@
+"""Factor 时点查询用例消费的最小存储能力。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_contract import FactorIdentity, FactorValue
+from quant_core.app.factor.schema.factor_query_result_schema import ProbeCellStatus
+
+
+class IFactorQueryStore(Protocol):
+    async def list_snapshot(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        instrument_ids: tuple[str, ...],
+        decision_time: datetime,
+        *,
+        dataset_revision: str | None = None,
+        as_of_on: date | None = None,
+    ) -> list[FactorValue]: ...
+
+    async def list_series(
+        self,
+        identity: FactorIdentity,
+        instrument_id: str,
+        start: datetime,
+        end: datetime,
+        decision_time: datetime,
+        *,
+        dataset_revision: str | None = None,
+    ) -> tuple[FactorValue, ...]: ...
+
+    async def probe_status(
+        self,
+        identities: tuple[FactorIdentity, ...],
+        instrument_ids: tuple[str, ...],
+        *,
+        target_as_of: date,
+        dataset_revision: str | None = None,
+    ) -> dict[tuple[tuple, str], ProbeCellStatus]: ...

quant_core/app/factor/interface/public/factor_diagnostics.py

@@ -0,0 +1,18 @@
+"""对研究公开的诊断数学接口。"""
+
+from decimal import Decimal
+from typing import Protocol
+
+from quant_core.app.factor.schema.diagnostic_types import CrossSection, FactorDiagnostics
+
+
+class IFactorDiagnostics(Protocol):
+    def analyze(
+        self,
+        sections: tuple[CrossSection, ...],
+        *,
+        quantiles: int = 5,
+        selections: tuple[tuple[str, ...], ...] = (),
+        comparison_values: dict[str, Decimal] | None = None,
+        horizon_sections: dict[int, tuple[CrossSection, ...]] | None = None,
+    ) -> FactorDiagnostics: ...

quant_core/app/factor/interface/public/factor_exposure_query.py

@@ -0,0 +1,12 @@
+"""研究和策略共享的 PIT 暴露读取契约。"""
+
+from datetime import datetime
+from typing import Protocol
+
+from quant_core.app.factor.schema.selection_types import SelectionExposure
+
+
+class IFactorExposureQuery(Protocol):
+    async def __call__(
+        self, instrument_ids: tuple[str, ...], decision_time: datetime
+    ) -> dict[str, SelectionExposure]: ...

quant_core/app/factor/interface/public/factor_local.py

@@ -0,0 +1,15 @@
+"""本地因子运行的跨域存取契约。"""
+
+from typing import Protocol
+from uuid import UUID
+
+from quant_core.common.local_run import LocalRunRecord
+
+
+class LocalFactorStore(Protocol):
+    def save(self, record: LocalRunRecord, values: dict | None = None) -> None: ...
+    def get(self, run_uuid: UUID) -> LocalRunRecord: ...
+    def list_runs(self, limit: int = 20, offset: int = 0) -> list[LocalRunRecord]: ...
+    def load_values(self, run_uuid: UUID) -> dict: ...
+
+    def list_values(self, run_uuid: UUID, limit: int = 100, offset: int = 0) -> list[dict]: ...

quant_core/app/factor/interface/public/factor_query.py

@@ -0,0 +1,57 @@
+"""Factor Query Protocol - 统一因子读取边界（T1 最小消费面，T4 实现）
+
+R1-1 契约收口：本 Protocol 是全系统唯一的因子只读消费面，方法签名与
+`FactorRuntimeService` 的公开实现逐字一致——`FactorRuntimeService` 必须
+真实结构满足本 Protocol（isinstance 守护测试），禁止再出现「Protocol 一套
+方法名、实现另一套」的假满足。
+
+AC-4：本 Protocol 只引用 Canonical Factor Contract（app/factor/schema），
+不引用 Tushare SDK、不引用具体 Repository——消费方（Strategy/Selection/Agent）
+通过它读取因子，不感知 Provider 与存储实现（依赖方向：下游 → 本协议 → Store）。
+
+与 Strategy 域 StrategyFactorProviderProtocol（本地计算推模式）的关系见
+TASK 文档 R1-1 Ownership 表：Strategy 域是生产端/消费端，因子身份与值的
+SSOT 在本域。
+"""
+
+from datetime import date, datetime
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.factor.constants import FactorFreshness
+from quant_core.app.factor.schema.factor_contract import FactorIdentity, FactorSnapshot, FactorValue
+
+
+@runtime_checkable
+class IFactorQuery(Protocol):
+    """Canonical Factor Store 的只读消费面（point-in-time 安全）
+
+    签名与 FactorRuntimeService 公开实现逐字一致（R1-1 守护测试 +
+    inspect 签名一致性守护）；R2-5 增补 target_as_of/freshness（截面
+    新鲜度策略），R2-2 增补 dataset_revision（旧数据集复现）。
+    """
+
+    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 时点可读的目标业务日截面"""
+        ...
+
+    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] 历史序列（只含 decision_time 可见值）"""
+        ...

quant_core/app/factor/interface/public/factor_selection.py

@@ -0,0 +1,20 @@
+"""策略与研究共享的因子选股能力契约。"""
+
+from typing import Protocol
+
+from quant_core.app.factor.schema.factor_contract import FactorSnapshot
+from quant_core.app.factor.schema.selection_types import (
+    SelectionDefinition,
+    SelectionExposure,
+    SelectionResult,
+)
+
+
+class IFactorSelection(Protocol):
+    def select(
+        self,
+        definition: SelectionDefinition,
+        universe: tuple[str, ...] | list[str],
+        snapshot: FactorSnapshot,
+        exposures: dict[str, SelectionExposure] | None = None,
+    ) -> SelectionResult: ...

quant_core/app/factor/schema/__init__.py

@@ -0,0 +1 @@
+"""Factor Domain Schema 层"""

quant_core/app/factor/schema/diagnostic_types.py

@@ -0,0 +1,42 @@
+"""因子研究诊断的来源无关值类型。"""
+
+from dataclasses import dataclass
+from datetime import date
+from decimal import Decimal
+
+
+@dataclass(frozen=True)
+class CrossSection:
+    as_of: date
+    factor_values: dict[str, Decimal]
+    forward_returns: dict[str, Decimal]
+
+
+@dataclass(frozen=True)
+class IcPoint:
+    as_of: date
+    ic: Decimal | None
+    rank_ic: Decimal | None
+    sample_size: int
+
+
+@dataclass(frozen=True)
+class QuantileReturn:
+    quantile: int
+    mean_return: Decimal | None
+    sample_size: int
+
+
+@dataclass(frozen=True)
+class DecayPoint:
+    lag: int
+    mean_rank_ic: Decimal | None
+
+
+@dataclass(frozen=True)
+class FactorDiagnostics:
+    ic_series: tuple[IcPoint, ...]
+    quantile_returns: tuple[QuantileReturn, ...]
+    decay: tuple[DecayPoint, ...]
+    selection_turnover: Decimal | None
+    factor_correlation: Decimal | None = None

quant_core/app/factor/schema/factor_artifact_schema.py

@@ -0,0 +1,36 @@
+"""Worker 因子产物，可由单一归档进程导入本地库。"""
+
+from datetime import datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from quant_core.common.local_run import LocalRunRecord
+
+
+class FactorArtifactValue(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    name: str
+    as_of: datetime
+    instrument_id: str
+    value: Decimal | None
+
+    @field_validator("as_of")
+    @classmethod
+    def aware(cls, value: datetime) -> datetime:
+        if value.utcoffset() is None:
+            raise ValueError("因子时间需要时区")
+        return value
+
+    @field_validator("value")
+    @classmethod
+    def finite(cls, value: Decimal | None) -> Decimal | None:
+        if value is not None and not value.is_finite():
+            raise ValueError("因子值必须有限")
+        return value
+
+
+class FactorArtifact(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    record: LocalRunRecord
+    values: tuple[FactorArtifactValue, ...]