quantnodes 3.0.0__py3-none-any.whl

QuantNodes/operators/math.py

@@ -0,0 +1,163 @@
+# coding=utf-8
+"""
+数学算子（代理层）
+
+基于 factor_functions/math_ops.py 的实现，提供统一的类接口。
+
+Available Operators:
+    - add: 加法
+    - sub: 减法
+    - mul: 乘法
+    - div: 除法
+    - log: 对数
+    - abs: 绝对值
+    - pow: 幂运算
+    - sqrt: 平方根
+    - sign: 符号
+    - clip: 裁剪
+    - fill_null: 填充空值
+    - nan_to_null: NaN 转 null
+
+Usage:
+    >>> math.add(pl.col("factor"), 1.0)
+    >>> math.mul(pl.col("factor"), 0.5)
+    >>> math.log(pl.col("factor"))
+"""
+
+from __future__ import annotations
+
+from typing import Union, Optional
+
+import polars as pl
+from polars import Expr
+
+from QuantNodes.factor_node.factor_functions.math_ops import (
+    log as _log,
+    log1p as _log1p,
+    abs as _abs,
+    sqrt as _sqrt,
+    sign as _sign,
+    pow as _pow,
+    clip as _clip,
+    fill_null as _fill_null,
+    fill_zero as _fill_zero,
+    nan_to_null as _nan_to_null,
+    ceil as _ceil,
+    floor as _floor,
+    sin as _sin,
+    cos as _cos,
+    tan as _tan,
+    arcsin as _arcsin,
+    arccos as _arccos,
+    arctan as _arctan,
+)
+
+
+class MathOperators:
+    """数学算子（代理层）"""
+
+    @staticmethod
+    def add(expr: Union[Expr, str], value: Union[float, Expr]) -> Expr:
+        if isinstance(expr, str):
+            expr = pl.col(expr)
+        return expr + value
+
+    @staticmethod
+    def sub(expr: Union[Expr, str], value: Union[float, Expr]) -> Expr:
+        if isinstance(expr, str):
+            expr = pl.col(expr)
+        return expr - value
+
+    @staticmethod
+    def mul(expr: Union[Expr, str], value: Union[float, Expr]) -> Expr:
+        if isinstance(expr, str):
+            expr = pl.col(expr)
+        return expr * value
+
+    @staticmethod
+    def div(expr: Union[Expr, str], value: Union[float, Expr]) -> Expr:
+        if isinstance(expr, str):
+            expr = pl.col(expr)
+        if isinstance(value, (int, float)):
+            return expr / (value + 1e-10)
+        else:
+            return expr / (value + 1e-10)
+
+    @staticmethod
+    def log(expr: Union[Expr, str], base: Optional[str] = None) -> Expr:
+        return _log(expr, base=base)
+
+    @staticmethod
+    def log1p(expr: Union[Expr, str]) -> Expr:
+        return _log1p(expr)
+
+    @staticmethod
+    def abs(expr: Union[Expr, str]) -> Expr:
+        return _abs(expr)
+
+    @staticmethod
+    def sqrt(expr: Union[Expr, str]) -> Expr:
+        return _sqrt(expr)
+
+    @staticmethod
+    def sign(expr: Union[Expr, str]) -> Expr:
+        return _sign(expr)
+
+    @staticmethod
+    def pow(expr: Union[Expr, str], exponent: float = 2.0) -> Expr:
+        return _pow(expr, exponent=exponent)
+
+    @staticmethod
+    def clip(expr: Union[Expr, str], lower: Optional[float] = None,
+             upper: Optional[float] = None) -> Expr:
+        return _clip(expr, lower=lower, upper=upper)
+
+    @staticmethod
+    def floor(expr: Union[Expr, str]) -> Expr:
+        return _floor(expr)
+
+    @staticmethod
+    def ceil(expr: Union[Expr, str]) -> Expr:
+        return _ceil(expr)
+
+    @staticmethod
+    def nan_to_null(expr: Union[Expr, str]) -> Expr:
+        return _nan_to_null(expr)
+
+    @staticmethod
+    def fill_null(expr: Union[Expr, str], value: Union[float, str] = 0.0) -> Expr:
+        return _fill_null(expr, value=value)
+
+    @staticmethod
+    def fill_zero(expr: Union[Expr, str]) -> Expr:
+        return _fill_zero(expr)
+
+    @staticmethod
+    def round(expr: Union[Expr, str], decimals: int = 0) -> Expr:
+        if isinstance(expr, str):
+            expr = pl.col(expr)
+        return expr.round(decimals)
+
+    @staticmethod
+    def sin(expr: Union[Expr, str]) -> Expr:
+        return _sin(expr)
+
+    @staticmethod
+    def cos(expr: Union[Expr, str]) -> Expr:
+        return _cos(expr)
+
+    @staticmethod
+    def tan(expr: Union[Expr, str]) -> Expr:
+        return _tan(expr)
+
+    @staticmethod
+    def arcsin(expr: Union[Expr, str]) -> Expr:
+        return _arcsin(expr)
+
+    @staticmethod
+    def arccos(expr: Union[Expr, str]) -> Expr:
+        return _arccos(expr)
+
+    @staticmethod
+    def arctan(expr: Union[Expr, str]) -> Expr:
+        return _arctan(expr)

QuantNodes/operators/proxy.py

@@ -0,0 +1,29 @@
+# coding=utf-8
+"""
+operators.proxy - 统一代理层
+
+本模块从 factor_functions 导出注册表 API，
+作为 operators 模块的统一代理入口。
+
+Agent 系统应从本模块导入，而非直接从 factor_functions 导入。
+"""
+
+from QuantNodes.factor_node.factor_functions import (
+    list_operators,
+    get_operator,
+    register_operator,
+    operator_info,
+    generate_documentation,
+    OperatorCategory,
+    _OPERATOR_REGISTRY,
+)
+
+__all__ = [
+    "list_operators",
+    "get_operator",
+    "register_operator",
+    "operator_info",
+    "generate_documentation",
+    "OperatorCategory",
+    "_OPERATOR_REGISTRY",
+]

QuantNodes/operators/registry.py

@@ -0,0 +1,144 @@
+# coding=utf-8
+"""
+operators.registry - 用户自定义算子隔离注册表
+
+用户通过 CustomOperator 注册的算子存储在此注册表，
+与内置 _OPERATOR_REGISTRY 完全隔离。
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+class _CustomOperatorRegistry:
+    """用户自定义算子隔离注册表"""
+
+    _registry: Dict[str, Dict[str, Dict[str, Any]]] = {
+        "point": {},
+        "time": {},
+        "section": {},
+        "multi_section": {},
+        "talib": {},
+    }
+    _aliases: Dict[str, Tuple[str, str]] = {}
+
+    @classmethod
+    def register(
+        cls,
+        category: str,
+        name: str,
+        func: Callable,
+        doc: str = "",
+        params: Optional[Dict[str, Any]] = None,
+        aliases: Optional[List[str]] = None,
+    ) -> None:
+        """注册算子到隔离注册表"""
+        try:
+            source = inspect.getsource(func)
+        except (OSError, TypeError):
+            source = ""
+
+        cls._registry.setdefault(category, {})
+        cls._registry[category][name] = {
+            "name": name,
+            "category": category,
+            "func": func,
+            "doc": doc or inspect.getdoc(func) or "",
+            "params": params or {},
+            "source": source,
+        }
+
+        for alias in (aliases or []):
+            cls._aliases[alias] = (name, category)
+
+    @classmethod
+    def register_alias(cls, alias: str, name: str, category: str) -> None:
+        """注册别名"""
+        cls._aliases[alias] = (name, category)
+
+    @classmethod
+    def get(cls, name: str, category: Optional[str] = None) -> Optional[Callable]:
+        """获取算子函数（支持别名）"""
+        if name in cls._aliases:
+            name, category = cls._aliases[name]
+
+        if category:
+            return cls._registry.get(category, {}).get(name, {}).get("func")
+
+        for cat in cls._registry:
+            if name in cls._registry[cat]:
+                return cls._registry[cat][name]["func"]
+        return None
+
+    @classmethod
+    def list(cls, category: Optional[str] = None) -> List[str]:
+        """列出算子名称"""
+        if category:
+            return list(cls._registry.get(category, {}).keys())
+        return [name for cat in cls._registry for name in cls._registry[cat]]
+
+    @classmethod
+    def info(cls, name: str) -> Optional[Dict[str, Any]]:
+        """获取算子详细信息"""
+        if name in cls._aliases:
+            name, category = cls._aliases[name]
+        for cat in cls._registry:
+            if name in cls._registry[cat]:
+                return cls._registry[cat][name]
+        return None
+
+    @classmethod
+    def unregister(cls, name: str, category: Optional[str] = None) -> bool:
+        """注销算子"""
+        if name in cls._aliases:
+            _, cat = cls._aliases.pop(name)
+            cls._registry.get(cat, {}).pop(name, None)
+            return True
+
+        if category:
+            removed = cls._registry.get(category, {}).pop(name, None)
+            return removed is not None
+
+        for cat in cls._registry:
+            if cls._registry[cat].pop(name, None):
+                return True
+        return False
+
+    @classmethod
+    def unregister_all(cls) -> int:
+        """注销所有自定义算子，返回数量"""
+        count = 0
+        for cat in cls._registry:
+            count += len(cls._registry[cat])
+            cls._registry[cat].clear()
+        cls._aliases.clear()
+        return count
+
+    @classmethod
+    def export_dict(cls) -> Dict[str, Dict[str, Dict[str, Any]]]:
+        """导出为字典"""
+        return cls._registry
+
+    @classmethod
+    def import_dict(cls, data: Dict[str, Dict[str, Dict[str, Any]]]) -> int:
+        """从字典导入，返回导入数量"""
+        count = 0
+        for category, operators in data.items():
+            for name, info in operators.items():
+                if "func" in info:
+                    cls.register(
+                        category,
+                        name,
+                        info["func"],
+                        info.get("doc", ""),
+                        info.get("params", {}),
+                    )
+                    count += 1
+        return count
+
+    @classmethod
+    def count(cls) -> int:
+        """返回注册的自定义算子数量"""
+        return len(cls.list())

QuantNodes/operators/section.py

@@ -0,0 +1,99 @@
+# coding=utf-8
+"""
+截面算子（代理层）
+
+基于 factor_functions/section_ops.py 的实现，提供统一的类接口。
+
+Available Operators:
+    - rank: 截面排名
+    - zscore: Z-score 标准化
+    - winsorize: 去极值
+    - neutralize: 行业中性
+    - neutralize_market: 市场中性
+    - scale: 归一化
+    - percentile: 百分位排名
+    - ic: 信息系数
+    - rank_ic: 秩信息系数
+    - group_norm: 分组标准化
+    - group_winsorize: 分组去极值
+
+Usage:
+    >>> sec.rank(pl.col("factor"))
+    >>> sec.zscore(pl.col("factor"))
+    >>> sec.winsorize(pl.col("factor"), 0.01, 0.01)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Union
+
+import polars as pl
+from polars import Expr
+
+if TYPE_CHECKING:
+    pass
+
+from QuantNodes.factor_node.factor_functions.section_ops import (
+    rank as _rank,
+    zscore as _zscore,
+    winsorize as _winsorize,
+    neutralize as _neutralize,
+    neutralize_market as _neutralize_market,
+    scale as _scale,
+    ic as _ic,
+    rank_ic as _rank_ic,
+    group_norm as _group_norm,
+    group_winsorize as _group_winsorize,
+)
+
+
+class SectionOperators:
+    """截面算子（代理层）"""
+
+    @staticmethod
+    def rank(expr: Union[Expr, str], method: str = "dense") -> Expr:
+        return _rank(expr, method=method)
+
+    @staticmethod
+    def zscore(expr: Union[Expr, str], eps: float = 1e-8) -> Expr:
+        return _zscore(expr, eps=eps)
+
+    @staticmethod
+    def winsorize(expr: Union[Expr, str], lower: float = 0.01, upper: float = 0.01,
+                  method: str = "quantile") -> Expr:
+        return _winsorize(expr, lower=lower, upper=upper, method=method)
+
+    @staticmethod
+    def neutralize(expr: Union[Expr, str], group: Union[Expr, str]) -> Expr:
+        return _neutralize(expr, group=group)
+
+    @staticmethod
+    def neutralize_market(expr: Union[Expr, str]) -> Expr:
+        return _neutralize_market(expr)
+
+    @staticmethod
+    def scale(expr: Union[Expr, str], method: str = "zscore") -> Expr:
+        return _scale(expr, method=method)
+
+    @staticmethod
+    def percentile(expr: Union[Expr, str]) -> Expr:
+        e = expr if isinstance(expr, Expr) else pl.col(expr)
+        col_name = expr if isinstance(expr, str) else "percentile"
+        return (e.rank() / e.count()).alias(col_name)
+
+    @staticmethod
+    def rank_ic(expr: Union[Expr, str], target: Union[Expr, str]) -> Expr:
+        return _rank_ic(expr, target=target)
+
+    @staticmethod
+    def ic(expr: Union[Expr, str], target: Union[Expr, str]) -> Expr:
+        return _ic(expr, target=target)
+
+    @staticmethod
+    def group_norm(expr: Union[Expr, str], group: Union[Expr, str], method: str = "zscore") -> Expr:
+        return _group_norm(expr, group=group, method=method)
+
+    @staticmethod
+    def group_winsorize(expr: Union[Expr, str], group: Union[Expr, str],
+                        lower: float = 0.01, upper: float = 0.01) -> Expr:
+        return _group_winsorize(expr, group=group, lower=lower, upper=upper)