quantnodes 3.0.0__py3-none-any.whl

QuantNodes/operators/__init__.py

@@ -0,0 +1,90 @@
+# coding=utf-8
+"""
+QuantNodes Operators - Polars 算子模块
+
+基于 Polars 的因子运算算子，提供简洁的表达式接口。
+
+Modules:
+    time_series: 时间序列算子 (ts_mean, ts_std, ts_corr...)
+    section: 截面算子 (rank, zscore, winsorize...)
+    math: 数学算子 (add, mul, log, pow...)
+    composite: 组合算子 (weighted_sum, combine...)
+    talib: TA-Lib 技术分析指标 (rsi, sma, macd, bbands, ...)
+
+Usage:
+    from QuantNodes.operators import ts, sec, math, talib_ops
+
+    # 时间序列
+    result = ts.ts_mean(pl.col("close"), 20)
+
+    # 截面
+    result = sec.rank(pl.col("factor"))
+
+    # 数学
+    result = math.add(pl.col("factor"), 1.0)
+
+    # TA-Lib
+    result = talib_ops.rsi(pl.col("close"), timeperiod=14)
+"""
+
+from .time_series import TimeSeriesOperators as _ts
+from .section import SectionOperators as _sec
+from .math import MathOperators as _math
+from .composite import CompositeOperators as _composite
+from .proxy import list_operators, get_operator, register_operator
+from .custom import CustomOperator, OperatorTemplate, point, time, section
+# PR-QN-3a (2026-06-21): Composite DAG re-exports
+from .composite_dag import (
+    composite_operator,
+    CompositeSpec,
+    ParamSpec,
+    is_composite_op,
+    get_composite_spec,
+    list_composite_ops,
+    get_composite_doc_for_llm,
+    load_composites_from_yaml,
+    _COMPOSITE_REGISTRY_POLARS,
+    _COMPOSITE_REGISTRY_PANDAS,
+)
+
+# PR-QN-3b (2026-06-21): 20 个内置 composite op (注册副作用)
+from . import composite_dag_ops  # noqa: F401 — 模块导入即注册
+
+# PR-QN-4 (2026-06-22): 20 个 pandas 镜像 composite op (注册副作用)
+from . import composite_dag_pandas_ops  # noqa: F401 — 模块导入即注册
+
+# PR-QN-4 (2026-06-22): Dual-Engine support
+from ._engine import Engine, detect_engine
+
+# Phase 3.2 (2026-06-22): 3 层注册表统一只读门面 (Facade)
+from .facade import OperatorFacade, operator_facade
+
+# 统一导出
+ts = _ts()
+sec = _sec()
+math = _math()
+composite = _composite()
+
+# TA-Lib (可选)
+try:
+    from .talib import TaLibOperators as _talib
+    talib_ops = _talib()
+except ImportError:
+    talib_ops = None
+
+__all__ = [
+    "ts", "sec", "math", "composite", "talib_ops",
+    "TimeSeriesOperators", "SectionOperators", "MathOperators", "CompositeOperators",
+    "list_operators", "get_operator", "register_operator",
+    "CustomOperator", "OperatorTemplate",
+    "point", "time", "section",
+    # PR-QN-3a (2026-06-21): Composite DAG
+    "composite_operator", "CompositeSpec", "ParamSpec",
+    "is_composite_op", "get_composite_spec", "list_composite_ops",
+    "get_composite_doc_for_llm", "load_composites_from_yaml",
+    # PR-QN-4 (2026-06-22): Dual-Engine
+    "Engine", "detect_engine",
+    "_COMPOSITE_REGISTRY_POLARS", "_COMPOSITE_REGISTRY_PANDAS",
+    # Phase 3.2 (2026-06-22): Operator Facade
+    "OperatorFacade", "operator_facade",
+]

QuantNodes/operators/_engine.py

@@ -0,0 +1,108 @@
+# coding=utf-8
+"""Dual-Engine support for Composite DAG operators (PR-QN-4, 2026-06-22)
+
+Provides engine detection for LLM-generated code and dual whitelists
+for YAML template validation (polars vs pandas, strict separation).
+
+Usage:
+    from QuantNodes.operators._engine import Engine, detect_engine
+
+    engine = detect_engine("import pandas as pd\\nresult = df.groupby('x').mean()")
+    assert engine == Engine.PANDAS
+
+    engine = detect_engine("import polars as pl\\nresult = pl.col('x').mean()")
+    assert engine == Engine.POLARS
+"""
+from __future__ import annotations
+
+import ast
+from enum import Enum
+from typing import Set
+
+
+class Engine(str, Enum):
+    POLARS = "polars"
+    PANDAS = "pandas"
+    AUTO = "auto"
+
+
+def detect_engine(code: str) -> Engine:
+    """Scan code for import statements to detect which engine is used.
+
+    Heuristics:
+      - `import polars as pl` or `from polars` → POLARS
+      - `import pandas as pd` or `from pandas` → PANDAS
+      - Both present → POLARS (default, faster path)
+      - Neither present → POLARS (safe default)
+
+    Returns:
+        Engine.POLARS or Engine.PANDAS (never AUTO)
+    """
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return Engine.POLARS
+
+    has_pl = False
+    has_pd = False
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == "polars" or alias.name.startswith("polars."):
+                    has_pl = True
+                elif alias.name == "pandas" or alias.name.startswith("pandas."):
+                    has_pd = True
+        elif isinstance(node, ast.ImportFrom):
+            if node.module and (node.module == "polars" or node.module.startswith("polars.")):
+                has_pl = True
+            elif node.module and (node.module == "pandas" or node.module.startswith("pandas.")):
+                has_pd = True
+
+    if has_pd and not has_pl:
+        return Engine.PANDAS
+    return Engine.POLARS
+
+
+# ===== YAML Template Whitelists (Strict Separation) =====
+
+ALLOWED_FUNC_NAMES_POLARS: Set[str] = {
+    # polars Expr methods
+    "col", "lit", "when", "then", "otherwise",
+    "abs", "log", "sqrt", "pow", "exp",
+    "rolling_mean", "rolling_std", "rolling_corr",
+    "rolling_sum", "rolling_min", "rolling_max", "rolling_median",
+    "ewm_mean", "ewm_std",
+    "shift", "diff", "pct_change", "rank",
+    "mean", "std", "sum", "min", "max", "median", "quantile",
+    "count", "first", "last",
+    "group_by", "over", "alias",
+    "clip", "fill_null", "fill_nan", "drop_nulls", "drop_nans",
+    "is_null", "is_nan", "is_not_null",
+    "round", "floor", "ceil",
+    "and_", "or_", "not_",
+}
+
+ALLOWED_FUNC_NAMES_PANDAS: Set[str] = {
+    # pandas Series/DataFrame methods
+    "groupby", "transform", "agg", "apply", "pipe",
+    "rolling", "expanding", "ewm",
+    "shift", "diff", "pct_change", "rank",
+    "fillna", "dropna", "isna", "notna", "isnull", "notnull",
+    "clip", "round", "abs", "astype",
+    "mean", "std", "sum", "min", "max", "median", "quantile",
+    "count", "first", "last",
+    "where", "mask", "assign",
+    "resample", "asfreq",
+    "merge", "join", "concat",
+    "reset_index", "set_index",
+    "head", "tail", "sort_values",
+    "to_numpy", "values",
+}
+
+__all__ = [
+    "Engine",
+    "detect_engine",
+    "ALLOWED_FUNC_NAMES_POLARS",
+    "ALLOWED_FUNC_NAMES_PANDAS",
+]

QuantNodes/operators/composite.py

@@ -0,0 +1,161 @@
+# coding=utf-8
+"""
+组合算子（代理层）
+
+基于 factor_functions/composite_ops.py 的实现，提供统一的类接口。
+
+Available Operators:
+    - weighted_sum: 加权求和
+    - weighted_avg: 加权平均
+    - max: 最大值
+    - min: 最小值
+    - abs_max: 绝对值最大
+    - combine: 组合两个因子
+    - blend: 混合两个因子
+    - select_top: 选择顶部
+    - filter_positive: 过滤正信号
+    - filter_negative: 过滤负信号
+    - abs_filter: 绝对值过滤
+    - rank_sort: 排名排序
+
+Usage:
+    >>> composite.weighted_sum([pl.col("f1"), pl.col("f2")], [0.6, 0.4])
+    >>> composite.blend("f1", "f2", 0.5)
+"""
+
+from __future__ import annotations
+
+from typing import Union, List, Optional
+
+import polars as pl
+from polars import Expr
+
+from QuantNodes.factor_node.factor_functions.composite_ops import (
+    blend as _blend,
+)
+
+
+class CompositeOperators:
+    """组合算子（代理层）"""
+
+    @staticmethod
+    def weighted_sum(factors: List[Union[Expr, str]], weights: List[float]) -> Expr:
+        exprs = [_ensure_expr(f) for f in factors]
+        weights_arr = pl.Series(weights)
+        weights_arr = weights_arr / weights_arr.sum()
+
+        first_factor = factors[0]
+        if isinstance(first_factor, str):
+            col_name = first_factor
+        elif hasattr(first_factor, 'meta') and hasattr(first_factor.meta, 'output_name'):
+            try:
+                col_name = first_factor.meta.output_name()
+            except Exception:
+                col_name = "result"
+        else:
+            col_name = "result"
+
+        return sum(e * w for e, w in zip(exprs, weights_arr)).alias(col_name)
+
+    @staticmethod
+    def weighted_avg(
+        factors: List[Union[Expr, str]], weights: Optional[List[float]] = None,
+    ) -> Expr:
+        if weights is None:
+            weights = [1.0] * len(factors)
+        return CompositeOperators.weighted_sum(factors, weights)
+
+    @staticmethod
+    def max(factors: List[Union[Expr, str]]) -> Expr:
+        exprs = [_ensure_expr(f) for f in factors]
+        first_factor = factors[0] if isinstance(factors[0], str) else "result"
+        return pl.max_horizontal(*exprs).alias(first_factor)
+
+    @staticmethod
+    def min(factors: List[Union[Expr, str]]) -> Expr:
+        exprs = [_ensure_expr(f) for f in factors]
+        first_factor = factors[0] if isinstance(factors[0], str) else "result"
+        return pl.min_horizontal(*exprs).alias(first_factor)
+
+    @staticmethod
+    def abs_max(factors: List[Union[Expr, str]]) -> Expr:
+        exprs = [_ensure_expr(f).abs() for f in factors]
+        first_factor = factors[0] if isinstance(factors[0], str) else "result"
+        return pl.max_horizontal(*exprs).alias(first_factor)
+
+    @staticmethod
+    def combine(factors: List[Union[Expr, str]], method: str = "add") -> Expr:
+        exprs = [_ensure_expr(f) for f in factors]
+        first_factor = factors[0] if isinstance(factors[0], str) else "result"
+
+        if method in ("add", "sum"):
+            return sum(exprs).alias(first_factor)
+        elif method == "avg":
+            return (sum(exprs) / len(exprs)).alias(first_factor)
+        elif method == "mul":
+            result = exprs[0]
+            for e in exprs[1:]:
+                result = result * e
+            return result.alias(first_factor)
+        elif method == "max":
+            return pl.max_horizontal(*exprs).alias(first_factor)
+        elif method == "min":
+            return pl.min_horizontal(*exprs).alias(first_factor)
+        return exprs[0].alias(first_factor)
+
+    @staticmethod
+    def blend(f1: Union[Expr, str], f2: Union[Expr, str], alpha: float = 0.5) -> Expr:
+        return _blend(f1, f2, alpha=alpha)
+
+    @staticmethod
+    def select_top(f: Union[Expr, str], n: int = 1, ascending: bool = False) -> Expr:
+        e = _ensure_expr(f)
+        col_name = f if isinstance(f, str) else "result"
+        if ascending:
+            return e.rank(method="dense").alias(col_name)
+        else:
+            return (e.count() - e.rank(method="dense") + 1).alias(col_name)
+
+    @staticmethod
+    def filter_positive(f: Union[Expr, str]) -> Expr:
+        e = _ensure_expr(f)
+        col_name = f if isinstance(f, str) else "result"
+        return pl.when(e > 0).then(pl.lit(0.0)).otherwise(e).alias(col_name)
+
+    @staticmethod
+    def filter_negative(f: Union[Expr, str]) -> Expr:
+        e = _ensure_expr(f)
+        col_name = f if isinstance(f, str) else "result"
+        return pl.when(e < 0).then(pl.lit(0.0)).otherwise(e).alias(col_name)
+
+    @staticmethod
+    def abs_filter(f: Union[Expr, str], threshold: float = 0.0) -> Expr:
+        e = _ensure_expr(f)
+        col_name = f if isinstance(f, str) else "result"
+        return pl.when(e.abs() > threshold).then(e).otherwise(pl.lit(0.0)).alias(col_name)
+
+    @staticmethod
+    def rank_sort(
+        factors: List[Union[Expr, str]], weights: Optional[List[float]] = None,
+    ) -> List[Expr]:
+        exprs = [_ensure_expr(f) for f in factors]
+
+        if weights is not None:
+            weights_arr = pl.Series(weights)
+            weights_arr = weights_arr / weights_arr.sum()
+            weighted_expr = sum(e * w for e, w in zip(exprs, weights_arr))
+            combined = weighted_expr
+        else:
+            combined = pl.max_horizontal(*exprs)
+
+        ranked = combined.rank()
+        return [
+            ranked.eq(i + 1).alias(f) if isinstance(f, str) else ranked.eq(i + 1)
+            for i, f in enumerate(factors)
+        ]
+
+
+def _ensure_expr(f: Union[Expr, str]) -> Expr:
+    if isinstance(f, str):
+        return pl.col(f)
+    return f