powerquant-cli 0.2.6__py3-none-any.whl

quant_cli/app/factor/repository/selection_local_repository.py

@@ -0,0 +1,67 @@
+"""selection 本地运行存取；短事务由本地连接上下文管理。"""
+
+from pathlib import Path
+from uuid import UUID
+
+from quant_core.common.local_run import LocalRunRecord
+
+from quant_cli.common.database.duckdb_connection import local_transaction
+
+
+class SelectionLocalRepository:
+    """只维护本领域的运行记录，查询使用数据库分页。"""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def save(self, record: LocalRunRecord) -> None:
+        with local_transaction(self.path) as connection:
+            connection.execute("""CREATE TABLE IF NOT EXISTS selection_local_run (
+                id BIGINT PRIMARY KEY, uuid UUID UNIQUE NOT NULL,
+                created_at TIMESTAMPTZ NOT NULL, document JSON NOT NULL)""")
+            existing = connection.execute(
+                "SELECT document FROM selection_local_run WHERE uuid = ?", [str(record.uuid)]
+            ).fetchone()
+            if existing is not None:
+                if LocalRunRecord.model_validate_json(existing[0]) != record:
+                    raise ValueError("同一运行 UUID 的记录不可覆盖")
+                return
+            connection.execute(
+                """INSERT INTO selection_local_run
+                SELECT COALESCE(MAX(id), 0) + 1, ?, ?, ? FROM selection_local_run""",
+                [str(record.uuid), record.created_at, record.model_dump_json()],
+            )
+
+    def get(self, run_uuid: UUID) -> LocalRunRecord:
+        if not self.path.is_file():
+            raise ValueError("运行记录不存在")
+        with local_transaction(self.path, read_only=True) as connection:
+            if not connection.execute(
+                "SELECT 1 FROM information_schema.tables WHERE table_name = ?",
+                ["selection_local_run"],
+            ).fetchall():
+                raise ValueError("运行记录不存在")
+            row = connection.execute(
+                "SELECT document FROM selection_local_run WHERE uuid = ?", [str(run_uuid)]
+            ).fetchone()
+        if row is None:
+            raise ValueError("运行记录不存在")
+        return LocalRunRecord.model_validate_json(row[0])
+
+    def list_runs(self, limit: int = 20, offset: int = 0) -> list[LocalRunRecord]:
+        if not 1 <= limit <= 1000 or offset < 0:
+            raise ValueError("分页参数非法")
+        if not self.path.is_file():
+            return []
+        with local_transaction(self.path, read_only=True) as connection:
+            if not connection.execute(
+                "SELECT 1 FROM information_schema.tables WHERE table_name = ?",
+                ["selection_local_run"],
+            ).fetchall():
+                return []
+            rows = connection.execute(
+                """SELECT document FROM selection_local_run
+                ORDER BY id DESC LIMIT ? OFFSET ?""",
+                [limit, offset],
+            ).fetchall()
+        return [LocalRunRecord.model_validate_json(row[0]) for row in rows]

quant_cli/app/factor/schema/local_selection_schema.py

@@ -0,0 +1,56 @@
+"""显式单次因子运行的本地选股请求。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+from uuid import UUID
+from zoneinfo import ZoneInfo
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from quant_core.app.factor.schema.selection_types import (
+    FactorTransform,
+    MissingPolicy,
+    SortDirection,
+)
+
+
+class LocalSelectionFactor(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    name: str = Field(min_length=1)
+    weight: Decimal = Field(gt=0, allow_inf_nan=False)
+    direction: SortDirection = SortDirection.DESC
+    transform: FactorTransform = Field(default_factory=FactorTransform)
+
+
+class LocalSelectionRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+    manifest_path: Path
+    factor_run_uuid: UUID
+    instrument_ids: tuple[str, ...] = Field(min_length=1)
+    factors: tuple[LocalSelectionFactor, ...] = Field(min_length=1)
+    decision_time: datetime
+    target_as_of: date
+    top_n: int = Field(default=10, ge=1)
+    missing_policy: MissingPolicy = MissingPolicy.EXCLUDE
+    exclude_st: bool = True
+    exclude_suspended: bool = True
+    exclude_limit_up: bool = True
+    max_rows: int = Field(default=1000000, ge=1)
+
+    @field_validator("manifest_path")
+    @classmethod
+    def absolute_path(cls, value: Path) -> Path:
+        return value.expanduser().resolve()
+
+    @model_validator(mode="after")
+    def validate_request(self) -> "LocalSelectionRequest":
+        if self.decision_time.utcoffset() is None:
+            raise ValueError("decision_time 必须带时区")
+        if self.target_as_of > self.decision_time.astimezone(ZoneInfo("Asia/Shanghai")).date():
+            raise ValueError("选股日期在决策时点之后")
+        if len(set(self.instrument_ids)) != len(self.instrument_ids):
+            raise ValueError("股票池重复")
+        names = [factor.name for factor in self.factors]
+        if len(set(names)) != len(names):
+            raise ValueError("选股因子重复")
+        return self

quant_cli/app/factor/service/factor_data_prepare_service.py

@@ -0,0 +1,181 @@
+"""PQFactor 本地入口：显式快照、交易时间轴与历史参与池，计算不联网。"""
+
+import hashlib
+import json
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from pqdata import MarketClient
+from pqdata.schema.history_schema import HistoryFactsQuery
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+from quant_core.app.data.service.calendar_coverage_service import build_calendar_coverage
+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.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
+
+from quant_cli.app.data.service.bar_cache_service import load_bar_snapshot
+from quant_cli.app.data.service.dataset_prepare_service import PreparedDataset, prepare_dataset
+
+
+async def prepare_local_factor_data(
+    factors: dict[str, FactorExpression],
+    client: MarketClient,
+    *,
+    instrument_ids: tuple[str, ...],
+    start: date,
+    end: date,
+    view: BarViewRequest,
+    cache_dir: Path,
+    max_rows: int,
+    max_history_days: int = 3660,
+) -> PreparedDataset:
+    """显式在线准备：按交易日历解析预热，复用回测数据准备和本地缓存。"""
+    if not factors or not instrument_ids or start > end or max_history_days < 1:
+        raise ValueError("因子数据准备参数非法")
+    lookback = max(factor.lookback for factor in factors.values())
+    fields = tuple(sorted(set().union(*(factor.required_fields for factor in factors.values()))))
+    FactorInputRequest(
+        instrument_ids=instrument_ids,
+        start=start,
+        end=end,
+        fields=fields,
+        lookback=lookback,
+        view=view,
+    )
+    if set(fields) - PANEL_UNITS.keys() or view.known_at is not None:
+        raise ValueError("当前快照仅支持量价字段和当前修订")
+    span = min(max_history_days, lookback * 3 + 7)
+    revision = None
+    while True:
+        lower = start - timedelta(days=span)
+        facts = await client.get_history_facts(
+            HistoryFactsQuery(
+                instrument_id=instrument_ids[0],
+                start=lower,
+                end=end,
+                revision=revision,
+            )
+        )
+        if revision is not None and facts.revision != revision:
+            raise ValueError("准备期间数据修订发生变化")
+        revision = facts.revision
+        coverage = build_calendar_coverage(
+            facts.instrument.exchange, lower, end, list(facts.calendar)
+        )
+        coverage.require_complete()
+        days = coverage.open_days
+        output = [day for day in days if start <= day <= end]
+        if not output:
+            raise ValueError("输出区间没有交易日")
+        first = days.index(output[0])
+        if first >= lookback - 1:
+            history_start = days[first - lookback + 1]
+            break
+        if span >= max_history_days:
+            raise ValueError("已达到历史查询上限，预热交易日仍不足")
+        span = min(span * 2, max_history_days)
+    cn = ZoneInfo("Asia/Shanghai")
+    if view.adjustment_type.value == "pre" and (
+        view.anchor_mode is None
+        or view.anchor_mode.value != "fixed_date"
+        or view.anchor_date is None
+        or not history_start <= view.anchor_date <= end
+    ):
+        raise ValueError("前复权需要准备范围内的固定日期锚点")
+    prepared = await prepare_dataset(
+        client,
+        instrument_ids=instrument_ids,
+        frequency="1d",
+        execution_frequency="1d",
+        start=datetime.combine(history_start, time.min, cn),
+        end=datetime.combine(end, time.max, cn),
+        adjustment_type=view.adjustment_type,
+        cache_dir=cache_dir,
+        lookback_days=0,
+        max_rows=max_rows,
+        revision=revision,
+    )
+    return prepared
+
+
+def execute_cached_factors(
+    factors: dict[str, FactorExpression],
+    manifest_path: Path,
+    *,
+    calendar: tuple[datetime, ...],
+    universe: dict[datetime, tuple[str, ...]],
+    start: datetime,
+    end: datetime,
+    max_rows: int,
+    output_instruments: tuple[str, ...] | None = None,
+) -> FactorBatchResult:
+    """原始价格快照试算；不声称复原供应商修订之前的历史知识状态。"""
+    snapshot, bars = load_bar_snapshot(manifest_path, max_rows)
+    query = snapshot.query
+    if query.frequency != "1d":
+        raise ValueError("首批本地公式入口仅支持日线")
+    if not calendar or tuple(sorted(set(calendar))) != calendar or set(calendar) != set(universe):
+        raise ValueError("必须提供有序完整交易日轴和逐日参与池")
+    if (
+        calendar[0] < query.start
+        or calendar[-1] > query.end
+        or start < query.start
+        or end > query.end
+    ):
+        raise ValueError("计算时间范围超出已准备快照")
+    ids = set(query.instrument_ids)
+    if any(not set(members).issubset(ids) for members in universe.values()):
+        raise ValueError("历史参与池包含快照未准备的证券")
+    required = set().union(*(factor.required_fields for factor in factors.values()))
+    if not required.issubset(PANEL_UNITS):
+        raise ValueError("本地行情快照未提供所需非量价字段")
+    lookup = {(bar.timestamp, bar.instrument_id): bar for bar in bars}
+    if any(timestamp not in universe for timestamp, _ in lookup):
+        raise ValueError("行情时间不属于提供的交易日轴")
+    rows = []
+    for timestamp in calendar:
+        for instrument_id in sorted(ids):
+            bar = lookup.get((timestamp, instrument_id))
+            fields: dict[str, Decimal | None] = dict.fromkeys(required)
+            if bar is not None and not bar.suspended:
+                for field in required:
+                    if field == "vwap":
+                        fields[field] = (
+                            bar.amount / bar.volume
+                            if bar.amount is not None and bar.volume > 0
+                            else None
+                        )
+                    else:
+                        value = getattr(bar, field)
+                        fields[field] = Decimal(value) if value is not None else None
+            rows.append(
+                FactorPanelRow(
+                    instrument_id=instrument_id,
+                    as_of=timestamp,
+                    available_at=query.end,
+                    eligible=instrument_id in universe[timestamp],
+                    fields=fields,
+                )
+            )
+    evidence = {key.isoformat(): sorted(value) for key, value in sorted(universe.items())}
+    panel = FactorPanel(
+        decision_time=query.end,
+        price_basis="raw",
+        universe_ref="explicit-historical-universe",
+        universe_revision=hashlib.sha256(json.dumps(evidence, sort_keys=True).encode()).hexdigest(),
+        market_revision=hashlib.sha256(
+            json.dumps(snapshot.model_dump(mode="json"), sort_keys=True).encode()
+        ).hexdigest(),
+        units={field: PANEL_UNITS[field] for field in required},
+        rows=tuple(rows),
+    )
+    return execute_factors(
+        factors, panel, start=start, end=end, output_instruments=output_instruments
+    )

quant_cli/app/factor/service/local_factor_query_service.py

@@ -0,0 +1,146 @@
+"""固定本地结果的 PIT 查询；不访问数据库或补算因子。"""
+
+from datetime import date, datetime, time
+from zoneinfo import ZoneInfo
+
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.factor.constants import FactorFreshness, FactorSourceKind, FactorStatus
+from quant_core.app.factor.schema.factor_contract import (
+    FactorIdentity,
+    FactorProvenance,
+    FactorSnapshot,
+    FactorSnapshotSelection,
+    FactorValue,
+)
+from quant_core.common.local_run import LocalRunRecord
+
+_CN = ZoneInfo("Asia/Shanghai")
+
+
+class LocalFactorQuery:
+    """持有一次运行的不可变行，按显式交易日历过滤可见性。"""
+
+    def __init__(
+        self, rows: tuple[FactorValue, ...], revision: str, trading_days: tuple[date, ...]
+    ) -> None:
+        self.rows, self.revision, self.trading_days = rows, revision, trading_days
+
+    def _check_revision(self, revision: str | None) -> None:
+        if revision is not None and revision != self.revision:
+            raise ValueError("本地因子运行批次不匹配")
+
+    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:
+        self._check_revision(dataset_revision)
+        decision_day = decision_time.astimezone(_CN).date()
+        target = target_as_of or max(
+            (day for day in self.trading_days if day < decision_day), default=decision_day
+        )
+        eligible = [
+            row
+            for row in self.rows
+            if row.identity in identities
+            and row.instrument_id in instrument_ids
+            and row.available_at <= decision_time
+            and row.as_of.astimezone(_CN).date() <= target
+        ]
+        if freshness == FactorFreshness.EXACT:
+            eligible = [row for row in eligible if row.as_of.astimezone(_CN).date() == target]
+        latest = {}
+        for row in sorted(eligible, key=lambda item: item.as_of):
+            latest[(row.identity.logical_key, row.instrument_id)] = row
+        return FactorSnapshot(
+            decision_time=decision_time,
+            values=tuple(latest.values()),
+            selection=FactorSnapshotSelection(
+                identities=tuple(identities),
+                instrument_ids=tuple(instrument_ids),
+                target_as_of=target,
+                freshness=freshness,
+                dataset_revision=self.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, ...]:
+        self._check_revision(dataset_revision)
+        return tuple(
+            row
+            for row in self.rows
+            if row.identity == identity
+            and row.instrument_id == instrument_id
+            and start <= row.as_of <= end
+            and row.available_at <= decision_time
+        )
+
+
+async def build_local_factor_query(
+    record: LocalRunRecord, values: dict, market: IMarketDataQuery, calendar_end: date
+) -> tuple[LocalFactorQuery, dict[str, FactorIdentity]]:
+    """日线结果保守采用下一交易日开盘可见；缺后续日历时拒绝推测。"""
+    revision = str(record.uuid)
+    aliases = {
+        name: FactorIdentity(
+            name=name,
+            source="local-python",
+            definition_version=record.provenance["definition_digest"],
+        )
+        for name in values
+    }
+    if record.provenance.get("published_definitions"):
+        aliases = {
+            name: FactorIdentity.model_validate(identity)
+            for name, identity in record.provenance["published_definitions"].items()
+        }
+        if set(aliases) != set(values):
+            raise ValueError("发布因子身份与结果名称不匹配")
+    rows = []
+    calendars: dict[str, list[date]] = {}
+    for name, cells in values.items():
+        for (timestamp, instrument), value in sorted(cells.items()):
+            day = timestamp.astimezone(_CN).date()
+            if instrument not in calendars:
+                info = await market.get_instrument(instrument)
+                calendar = await market.list_trading_days(info.exchange, day, calendar_end)
+                calendars[instrument] = sorted(
+                    {item.trade_date for item in calendar if item.is_open}
+                )
+            future = [item for item in calendars[instrument] if item > day]
+            if not future:
+                # 最后一个快照交易日的结果不能凭空生成后续可见时间。
+                continue
+            rows.append(
+                FactorValue(
+                    identity=aliases[name],
+                    instrument_id=instrument,
+                    as_of=timestamp,
+                    available_at=datetime.combine(future[0], time(9, 30), _CN),
+                    value=value,
+                    status=FactorStatus.AVAILABLE if value is not None else FactorStatus.MISSING,
+                    provenance=FactorProvenance(
+                        source_kind=FactorSourceKind.LOCAL_CALCULATOR,
+                        provider_id="local-factor",
+                        dataset_revision=revision,
+                        content_digest=record.provenance["definition_digest"],
+                    ),
+                )
+            )
+    return LocalFactorQuery(
+        tuple(rows), revision, tuple(sorted({day for days in calendars.values() for day in days}))
+    ), aliases

quant_cli/app/factor/service/local_factor_service.py

@@ -0,0 +1,120 @@
+"""本地因子公开用例：计算不打开数据库，归档依赖显式存取协议。"""
+
+import logging
+from uuid import UUID
+
+from quant_core.app.factor.computation.factor_source_loader import load_formulas
+from quant_core.app.factor.interface.public.factor_local import LocalFactorStore
+from quant_core.app.factor.schema.local_factor_schema import LocalFactorRequest
+from quant_core.app.factor.service.factor_local_execution_service import execute_local_factors
+from quant_core.common.local_run import LocalRunRecord, RunStatus, content_digest
+
+from quant_cli.app.data.service.dataset_load_service import load_dataset
+from quant_cli.common.utils.runtime_environment import runtime_versions
+
+
+async def compute_local_factor(request: LocalFactorRequest) -> tuple[LocalRunRecord, dict]:
+    """复用既有输入与算子，返回结果和来源；计算失败形成可归档记录。"""
+    record = LocalRunRecord(
+        request=request.model_dump(mode="json"),
+        provenance={
+            "source_digest": content_digest(request.source),
+            "environment": runtime_versions(),
+        },
+    )
+    try:
+        manifest = request.manifest_path.read_text(encoding="utf-8")
+        market, _ = load_dataset(request.manifest_path, request.max_rows)
+        record.provenance.update(
+            manifest_digest=content_digest(manifest), market_revision=market.revision
+        )
+        if request.definitions:
+            from quant_core.app.factor.service.published_factor_execution_service import (
+                execute_published_factors,
+            )
+
+            result = await execute_published_factors(request, market)
+            record.provenance["published_definitions"] = {
+                item.definition.identity.name: item.definition.identity.model_dump(mode="json")
+                for item in request.definitions
+            }
+            record.provenance["published_digests"] = {
+                item.definition.identity.name: item.content_digest for item in request.definitions
+            }
+        else:
+            result = await execute_local_factors(
+                load_formulas(request.source),
+                market,
+                instrument_ids=request.instrument_ids,
+                start=request.start,
+                end=request.end,
+                view=request.view,
+                exclude_st=request.exclude_st,
+            )
+        record.provenance.update(
+            input_digest=result.input_digest, definition_digest=result.definition_digest
+        )
+        record.result = {
+            "factors": list(result.values),
+            "lookback": result.lookback,
+            "cells": sum(len(cells) for cells in result.values.values()),
+        }
+        return record, result.values
+    except Exception as exc:
+        logging.getLogger(__name__).exception("本地计算失败")
+        record.status, record.error = RunStatus.FAILED, str(exc)
+        return record, {}
+
+
+async def run_local_factor(request: LocalFactorRequest, store: LocalFactorStore) -> LocalRunRecord:
+    """先计算、后短事务归档；归档失败直接传播，不宣称计算任务成功。"""
+    record, values = await compute_local_factor(request)
+    store.save(record, values)
+    return record
+
+
+def load_factor_result(store: LocalFactorStore, run_uuid: UUID) -> tuple[LocalRunRecord, dict]:
+    """研究与回测通过本公开用例读取因子产物。"""
+    record = store.get(run_uuid)
+    if record.status != RunStatus.COMPLETED:
+        raise ValueError("因子运行未成功")
+    return record, store.load_values(run_uuid)
+
+
+def decode_factor_artifact(text: str) -> tuple[LocalRunRecord, dict]:
+    """校验 Worker 产物后由单写入入口归档，不信任外部文件元数据。"""
+    import json
+
+    from quant_core.app.factor.schema.factor_artifact_schema import FactorArtifact
+
+    envelope = json.loads(text)
+    if envelope.get("format_version") != 1 or envelope.get("kind") != "factor":
+        raise ValueError("不支持的因子产物格式")
+    payload = envelope["payload"]
+    canonical = json.dumps(payload, sort_keys=True, ensure_ascii=False, allow_nan=False)
+    if envelope.get("sha256") != content_digest(canonical):
+        raise ValueError("因子产物摘要不匹配")
+    artifact = FactorArtifact.model_validate(payload)
+    values: dict = {}
+    for row in artifact.values:
+        cells = values.setdefault(row.name, {})
+        key = (row.as_of, row.instrument_id)
+        if key in cells:
+            raise ValueError("因子产物包含重复单元")
+        cells[key] = row.value
+    if artifact.record.status == RunStatus.COMPLETED:
+        if (
+            set(values) != set(artifact.record.result["factors"])
+            or sum(len(cells) for cells in values.values()) != artifact.record.result["cells"]
+        ):
+            raise ValueError("因子产物与运行摘要不一致")
+    elif values:
+        raise ValueError("失败产物不得包含成功因子值")
+    return artifact.record, values
+
+
+def import_factor_artifact(text: str, store: LocalFactorStore) -> LocalRunRecord:
+    """由单一归档入口导入已校验产物。"""
+    record, values = decode_factor_artifact(text)
+    store.save(record, values)
+    return record