quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/cache_utils.py

@@ -0,0 +1,150 @@
+# -*- coding: utf-8 -*-
+"""缓存工具函数
+
+从 FactorOperation.py 中提取的通用缓存操作函数，消除重复代码。
+"""
+import os
+import shelve
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+
+def create_std_data(
+    dts: List[Any],
+    ids: List[Any],
+    data_type: str,
+) -> np.ndarray:
+    """创建标准数据数组
+
+    Args:
+        dts: 时间点列表
+        ids: ID 列表
+        data_type: 数据类型 ("double", "string", "object")
+
+    Returns:
+        填充了默认值的 numpy 数组
+    """
+    dtype = "float" if data_type == "double" else "O"
+    fill = np.nan if data_type == "double" else None
+    return np.full(shape=(len(dts), len(ids)), fill_value=fill, dtype=dtype)
+
+
+def create_empty_dataframe(
+    dts: List[Any],
+    ids: List[Any],
+    data_type: str,
+    include_index: bool = True,
+) -> pd.DataFrame:
+    """创建空 DataFrame
+
+    Args:
+        dts: 时间点列表
+        ids: ID 列表
+        data_type: 数据类型 ("double", "string", "object")
+        include_index: 是否包含索引（当 dts 为空时为 False）
+
+    Returns:
+        空的 DataFrame
+    """
+    dtype = "float" if data_type == "double" else "O"
+    if include_index:
+        return pd.DataFrame(index=dts, columns=ids, dtype=dtype)
+    return pd.DataFrame(columns=ids, dtype=dtype)
+
+
+def partition_ids_for_pid(
+    operation_mode: Any,
+    ids: Optional[List[Any]],
+    pid: str,
+) -> List[Any]:
+    """按 PID 分区 ID 列表
+
+    Args:
+        operation_mode: 运算模式对象
+        ids: 原始 ID 列表，None 表示使用该 PID 的全部 ID
+        pid: 进程 ID
+
+    Returns:
+        该 PID 对应的 ID 子列表
+    """
+    from QuantNodes.core.tools import partition_list_moving_sampling
+
+    if ids is None:
+        return list(operation_mode._PID_IDs.get(pid, []))
+    return partition_list_moving_sampling(ids, len(operation_mode._PIDs))[
+        operation_mode._PIDs.index(pid)
+    ]
+
+
+def write_cache_file(
+    operation_mode: Any,
+    pid: str,
+    factor_name: str,
+    factor_id: int,
+    std_data: pd.DataFrame,
+    ids: List[Any],
+    append: bool = False,
+) -> None:
+    """写入 shelve 缓存文件
+
+    Args:
+        operation_mode: 运算模式对象
+        pid: 进程 ID
+        factor_name: 因子名称
+        factor_id: 因子唯一 ID
+        std_data: 标准数据 DataFrame
+        ids: ID 列表
+        append: 是否追加模式（用于 SectionOperation/PanelOperation 写入所有 PID）
+    """
+    cache_dir = operation_mode._CacheDataDir + os.sep + pid
+    os.makedirs(cache_dir, exist_ok=True)
+    cache_path = cache_dir + os.sep + factor_name + str(factor_id)
+
+    with operation_mode._PID_Lock.get(pid, _DummyLock()):
+        with shelve.open(cache_path) as cache_file:
+            if append and "StdData" in cache_file:
+                cache_file["StdData"] = pd.concat(
+                    [cache_file["StdData"], std_data.loc[:, ids]]
+                ).sort_index()
+            else:
+                cache_file["StdData"] = std_data
+            cache_file["_QN_IDs"] = ids
+
+
+def write_cache_files_for_all_pids(
+    operation_mode: Any,
+    pid_ids: Dict[str, List[Any]],
+    factor_name: str,
+    factor_id: int,
+    std_data: pd.DataFrame,
+) -> None:
+    """为所有 PID 写入缓存文件（SectionOperation/PanelOperation 使用）
+
+    Args:
+        operation_mode: 运算模式对象
+        pid_ids: {PID: [ID]} 映射
+        factor_name: 因子名称
+        factor_id: 因子唯一 ID
+        std_data: 标准数据 DataFrame
+    """
+    for i_pid, i_ids in pid_ids.items():
+        write_cache_file(
+            operation_mode=operation_mode,
+            pid=i_pid,
+            factor_name=factor_name,
+            factor_id=factor_id,
+            std_data=std_data,
+            ids=i_ids,
+            append=True,
+        )
+
+
+class _DummyLock:
+    """空锁，用于单进程模式"""
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass

QuantNodes/core/cond_builder.py

@@ -0,0 +1,53 @@
+# coding=utf-8
+"""
+Cond DSL 入口构建器
+
+提供简洁的表达式构建 API：
+    Cond('close') > 50           # 按列名访问
+    Cond.attr('metrics').sharpe  # 按属性名访问
+    Cond['close']                # 下标访问
+    Cond.close                   # 属性访问
+"""
+
+from typing import Any
+
+from QuantNodes.core.expression import (
+    ExpressionBuilder,
+    InputExpr,
+    VariableExpr,
+    AttributeExpr,
+    ConstantExpr,
+)
+
+
+class _CondBuilder:
+    """Cond 入口构建器 - 只在入口处提供特殊语法"""
+
+    def __call__(self, name: str) -> ExpressionBuilder:
+        """Cond('column_name') - 按列/变量名访问"""
+        return ExpressionBuilder(VariableExpr(name))
+
+    def attr(self, name: str) -> ExpressionBuilder:
+        """Cond.attr('metrics') - 按属性名访问"""
+        return ExpressionBuilder(AttributeExpr(InputExpr(), name))
+
+    def constant(self, value: Any) -> ExpressionBuilder:
+        """常量值"""
+        return ExpressionBuilder(ConstantExpr(value))
+
+    def __getattr__(self, name: str) -> ExpressionBuilder:
+        """支持 Cond.metrics 形式的属性访问"""
+        return ExpressionBuilder(AttributeExpr(InputExpr(), name))
+
+    def __getitem__(self, key: Any) -> ExpressionBuilder:
+        """支持下标访问 Cond['close']"""
+        return ExpressionBuilder(VariableExpr(key))
+
+    @property
+    def input(self) -> ExpressionBuilder:
+        """返回输入数据本身"""
+        return ExpressionBuilder(InputExpr())
+
+
+# 全局单例
+Cond = _CondBuilder()

QuantNodes/core/config.py

@@ -0,0 +1,170 @@
+# coding=utf-8
+"""
+core/config.py — **库级配置** (Tier 1: Library)
+
+本模块提供 QuantNodes 包代码全局使用的配置。
+
+配置分层 (Configuration Tiers):
+    ┌─────────────────────────────────────────────────────────┐
+    │ Tier 3: YAML 策略配置                                      │
+    │   → QuantNodes.agent.config (ConfigLoader/ConfigExecutor) │
+    ├─────────────────────────────────────────────────────────┤
+    │ Tier 2: API 服务器配置                                     │
+    │   → api.config.Settings (CORS, VERSION, AGENT_PROVIDER)  │
+    ├─────────────────────────────────────────────────────────┤
+    │ Tier 1: 库级配置 ← 本文件                                  │
+    │   → core.config.Settings (MySQL/CH/DuckDB/LLM/缓存/回测)  │
+    └─────────────────────────────────────────────────────────┘
+
+字段说明:
+    - project_name / debug / log_level: 项目级
+    - mysql / clickhouse / duckdb: 数据库连接
+    - llm: LLM 客户端配置 (api_key, base_url, model, timeout...)
+    - default_commission / default_slippage: 回测默认值
+    - cache_enabled / cache_ttl: 缓存策略
+
+环境变量:
+    前缀 QUANTNODES_, 分隔符 __, 如 QUANTNODES__LLM__API_KEY=xxx
+    同时从 .env 加载。
+
+同步关系:
+    - api 层通过 api.services.settings_service.sync_core_config()
+      将 .agent/settings.json 的值同步到本单例 (in-memory)
+    - 本文件 load_from_settings() 也从 .agent/settings.json 加载
+"""
+
+import json
+from typing import Optional, Dict, Any
+from functools import lru_cache
+from pathlib import Path
+from pydantic_settings import BaseSettings
+
+from QuantNodes.constants import DEFAULT_LLM_MODEL, DEFAULT_LLM_BASE_URL
+
+
+class DatabaseConfig(BaseSettings):
+    """数据库配置"""
+    host: str = "localhost"
+    port: int = 3306
+    user: str = "root"
+    password: str = ""
+    database: str = "quant"
+    charset: str = "utf8mb4"
+    echo: bool = False
+    pool_size: int = 10
+    max_overflow: int = 20
+
+
+class ClickHouseConfig(BaseSettings):
+    """ClickHouse 配置"""
+    host: str = "localhost"
+    port: int = 8123
+    user: str = "default"
+    password: str = ""
+    database: str = "default"
+    compression: bool = True
+    secure: bool = False
+
+
+class DuckDBConfig(BaseSettings):
+    """DuckDB 配置"""
+    path: str = ":memory:"
+    read_only: bool = False
+
+
+class LLMConfig(BaseSettings):
+    """LLM 配置"""
+    api_key: Optional[str] = None
+    base_url: str = DEFAULT_LLM_BASE_URL
+    model: str = DEFAULT_LLM_MODEL
+    timeout: int = 60
+    max_retries: int = 3
+    max_tokens: int = 102400
+    providers: Dict[str, Any] = {}
+
+
+class Settings(BaseSettings):
+    """全局配置"""
+
+    # 项目配置
+    project_name: str = "QuantNodes"
+    debug: bool = True
+    log_level: str = "INFO"
+
+    # 数据库
+    mysql: DatabaseConfig = DatabaseConfig()
+    clickhouse: ClickHouseConfig = ClickHouseConfig()
+    duckdb: DuckDBConfig = DuckDBConfig()
+
+    # LLM
+    llm: LLMConfig = LLMConfig()
+
+    # 回测默认参数
+    default_commission: float = 0.001  # 千分之一手续费
+    default_slippage: float = 0.001   # 千分之一滑点
+
+    # 缓存配置
+    cache_enabled: bool = True
+    cache_ttl: int = 3600  # 1小时
+
+    model_config = {
+        "env_prefix": "QUANTNODES_",
+        "env_file": ".env",
+        "env_nested_delimiter": "__",
+        "extra": "ignore",
+    }
+
+    def to_dict(self) -> Dict[str, Any]:
+        """转为字典，隐藏敏感信息"""
+        data = self.model_dump()
+
+        # 隐藏密码
+        if 'mysql' in data and 'password' in data['mysql']:
+            data['mysql']['password'] = '***'
+        if 'clickhouse' in data and 'password' in data['clickhouse']:
+            data['clickhouse']['password'] = '***'
+        if 'llm' in data and 'api_key' in data['llm']:
+            data['llm']['api_key'] = '***' if data['llm']['api_key'] else None
+
+        return data
+
+    def load_from_settings(self) -> None:
+        """Load LLM and backtest settings from .agent/settings.json
+        (single source of truth)
+        """
+        settings_file = Path(".agent/settings.json")
+        if not settings_file.exists():
+            return
+        try:
+            data = json.loads(settings_file.read_text(encoding="utf-8"))
+            agent = data.get("agent", {})
+            if agent.get("api_key"):
+                self.llm.api_key = agent["api_key"]
+            if agent.get("api_base"):
+                self.llm.base_url = agent["api_base"]
+            if agent.get("model"):
+                self.llm.model = agent["model"]
+            if "llm_timeout" in agent:
+                self.llm.timeout = agent["llm_timeout"]
+            if "llm_max_retries" in agent:
+                self.llm.max_retries = agent["llm_max_retries"]
+            if "max_tokens" in agent:
+                self.llm.max_tokens = agent["max_tokens"]
+            if "providers" in agent:
+                self.llm.providers = agent["providers"]
+            backtest = data.get("backtest", {})
+            if "default_commission" in backtest:
+                self.default_commission = backtest["default_commission"]
+        except Exception:
+            pass
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """获取全局配置（单例）"""
+    s = Settings()
+    s.load_from_settings()
+    return s
+
+
+settings = get_settings()

QuantNodes/core/constants.py

@@ -0,0 +1,48 @@
+"""QuantNodes 核心常量 — 跨模块统一的常量定义。
+
+修复 4 路常量漂移 (H7+H8):
+  - BASE_FEATURE_NAMES: feedback/channels.py 与 quality_gate/complexity.py 漂移
+  - METRIC_KEYS: feedback/dataclass + trajectory/entry + trajectory/pool 3 处定义
+  - PARQUET_COLUMNS: trajectory/pool 14 字段, 复用 METRIC_KEYS + 6 业务字段
+"""
+from __future__ import annotations
+
+from typing import FrozenSet, Tuple
+
+
+# ============================================================================
+# H7: 基础特征名 (统一 feedback + quality_gate)
+# ============================================================================
+# 包含 13 个核心字段 + 2 个扩展字段 (industry, cap) = 15 个
+# 注: 此前 feedback/channels.py 缺 industry/cap, quality_gate/complexity.py 含全部 15
+BASE_FEATURE_NAMES: FrozenSet[str] = frozenset({
+    "open", "high", "low", "close", "volume", "amount",
+    "vwap", "turnover", "mv_float", "total_mv", "circ_mv",
+    "returns",  # 日收益率（从 close 计算）
+    "returns", "vwap_adj",
+    "industry", "cap",  # 扩展字段
+})
+
+
+# ============================================================================
+# H8: Metric 键 (统一 4 处定义)
+# ============================================================================
+# 6 个标准指标 — 出现在 Parquet schema + entry.metrics 序列化
+METRIC_KEYS: Tuple[str, ...] = (
+    "ic_mean", "rank_ic_mean", "sharpe", "arr", "mdd", "calmar",
+)
+
+# 9 个扩展指标 — 出现在 FactorFeedback.metadata (来自 result dict)
+EXTENDED_METRIC_KEYS: Tuple[str, ...] = (
+    "ic", "rank_ic", "sharpe", "arr", "mdd", "calmar",
+    "turnover", "win_rate", "ic_ir",
+)
+
+
+# ============================================================================
+# TrajectoryPool Parquet 业务列 (与 METRIC_KEYS 集成)
+# ============================================================================
+PARQUET_COLUMNS: Tuple[str, ...] = (
+    "entry_id", "round_idx", "operation", "parent_ids",
+    "decision", "duration_ms", "timestamp", "factor_name", "summary",
+) + METRIC_KEYS