quantnodes 3.0.0__py3-none-any.whl

QuantNodes/__init__.py

@@ -0,0 +1,15 @@
+# coding=utf-8
+"""
+QuantNodes - AI-native quantitative research framework
+"""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+    try:
+        __version__ = _pkg_version("quantnodes")
+    except PackageNotFoundError:
+        __version__ = "0.0.0+local"
+except ImportError:
+    __version__ = "0.0.0+local"
+
+__author__ = 'sn0wfree'

QuantNodes/__main__.py

@@ -0,0 +1,14 @@
+# coding=utf-8
+"""
+QuantNodes CLI entry point
+
+Usage:
+    python -m quantnodes init
+    python -m quantnodes run
+    quantnodes --version
+    quantnodes --help
+"""
+
+if __name__ == "__main__":
+    from QuantNodes.cli import main
+    main()

QuantNodes/agent/__init__.py

@@ -0,0 +1,158 @@
+# coding=utf-8
+"""
+QuantNodes Agent 系统
+
+基于 HKUDS/nanobot 0.2.1 上游 (PyPI: ``nanobot-ai>=0.2.1,<0.3.0``) 的量化研究智能体。
+
+v3.0.0 架构变更（Path A: 直接消费上游）：
+- 核心运行时由本地复刻 → 改为包装 ``Nanobot.from_config``（见 ``nanobot_bridge.py``）
+- 量化专属 Dream 钩子见 ``QuantNodes.agent.core.quant_dream``
+- 15 个量化工具父类改为 ``nanobot.agent.tools.base.Tool``（见 ``tools/base.py``）
+- workspace 由 ``.quant_agent/`` → ``.agent/``（上游默认约定）
+
+**v3.0.0 重要变更（Stage 5.3）**：``nanobot-ai`` 改为 **可选依赖**
+（``pip install 'quantnodes[agent]'``）。未装时：
+- ``NANOBOT_AVAILABLE = False``
+- ``Agent`` 类的属性访问抛 ``NanobotNotInstalled``
+- 量化工具库（Wiki / Factor / Backtest / Strategy）完全可用
+- MCP server、API、CLI 等不依赖 nanobot 的部分正常启动
+
+Usage (向后兼容 v2.x 签名):
+    from QuantNodes.agent import Agent, NANOBOT_AVAILABLE
+
+    if NANOBOT_AVAILABLE:
+        agent = Agent(workspace=".agent", config={"model": "gpt-4o"})
+        response = await agent.run("帮我生成一个动量策略")
+    else:
+        # 量化工具库仍可用
+        from QuantNodes.research.wiki import WikiFactorProxy
+        wiki = WikiFactorProxy()
+        factor = await wiki.get("momentum_20")
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from QuantNodes.core.path_utils import ensure_dir
+
+__version__ = "3.0.0"
+
+# ----------------------------------------------------------------------------
+# Optional-dependency guard
+# ----------------------------------------------------------------------------
+#
+# v3.0.0 之前，``nanobot-ai`` 是强制依赖。从 Stage 5.3 起改为 ``[agent]`` extras：
+# - ``pip install quantnodes``            → 纯量化工具库
+# - ``pip install 'quantnodes[agent]'``   → + nanobot agent / WebUI / MCP
+# - ``pip install 'quantnodes[all]'``     → 装齐所有 extras
+#
+# 顶层 import 任何 nanobot 符号必须先检查 ``NANOBOT_AVAILABLE``，否则
+# ``from QuantNodes.agent import Agent`` 在未装 extras 时会 ImportError。
+NANOBOT_AVAILABLE: bool = True
+NANOBOT_IMPORT_ERROR: str | None = None
+_NANOBOT_PROBE: Any = None
+
+# Probe: try to import a real nanobot submodule, not just the top-level
+# namespace. The top-level `nanobot` may exist as a namespace package
+# (e.g. with just a `bridge/` subpackage) but the `nanobot.agent` submodule
+# could be missing — in which case the agent runtime is not usable.
+# We probe a known-deep symbol: ``nanobot.agent.tools.base.Tool``.
+try:
+    from nanobot.agent.tools.base import Tool as _ProbeTool  # noqa: F401
+    NANOBOT_AVAILABLE = True
+    del _ProbeTool
+except ImportError as _e:  # pragma: no cover - exercised by the import
+    NANOBOT_AVAILABLE = False
+    NANOBOT_IMPORT_ERROR = str(_e)
+
+
+class NanobotNotInstalled(ImportError):
+    """Raised when user code touches a nanobot-only symbol without [agent] extra.
+
+    The error message is tailored to be friendly: it tells the user exactly
+    which pip extra to install.
+    """
+
+    def __init__(self, symbol: str = "Agent"):
+        msg = (
+            f"{symbol} requires the optional 'agent' extra. "
+            "Install it with:  pip install 'quantnodes[agent]'  (or  'quantnodes[all]')"
+        )
+        if NANOBOT_IMPORT_ERROR:
+            msg += f"\nUnderlying error: {NANOBOT_IMPORT_ERROR}"
+        super().__init__(msg)
+
+
+# ----------------------------------------------------------------------------
+# Re-exports (lazy where nanobot is required)
+# ----------------------------------------------------------------------------
+if NANOBOT_AVAILABLE:
+    from .nanobot_bridge import Agent  # noqa: E402
+    from .core.quant_dream import (  # noqa: E402
+        QuantDreamHook,
+        QuantDreamInsight,
+        DreamEngine,
+    )
+    from .tools import register_all_quant_tools  # noqa: E402
+else:
+    # Provide a stub for ``Agent`` so ``from QuantNodes.agent import Agent`` does
+    # not raise at import time. The stub raises ``NanobotNotInstalled`` only when
+    # the user actually tries to *instantiate* or *attribute-access* it.
+    class _NanobotUnavailableProxy:
+        """Proxy that raises ``NanobotNotInstalled`` on any access.
+
+        Implemented via ``__getattr__`` (PEP 562) so that the import itself
+        succeeds — only attribute access triggers the error. This keeps
+        ``from QuantNodes.agent import Agent`` working everywhere; the user's
+        first real call (``Agent(...)`` or ``Agent.some_attr``) gets the
+        friendly error message.
+        """
+
+        _PROXY_SYMBOLS = {
+            "Agent",
+            "QuantDreamHook",
+            "QuantDreamInsight",
+            "DreamEngine",
+            "register_all_quant_tools",
+        }
+
+        def __getattr__(self, name: str) -> Any:
+            if name in self._PROXY_SYMBOLS:
+                raise NanobotNotInstalled(name)
+            raise AttributeError(
+                f"module {__name__!r} has no attribute {name!r} (nanobot-ai not installed)"
+            )
+
+        def __call__(self, *args: Any, **kwargs: Any) -> Any:  # pragma: no cover
+            raise NanobotNotInstalled("Agent")
+
+    _proxy = _NanobotUnavailableProxy()
+    Agent = _proxy  # type: ignore[assignment]
+    QuantDreamHook = _proxy  # type: ignore[assignment]
+    QuantDreamInsight = _proxy  # type: ignore[assignment]
+    DreamEngine = _proxy  # type: ignore[assignment]
+    register_all_quant_tools = _proxy  # type: ignore[assignment]
+
+    # Emit a one-time DeprecationWarning-ish info on import
+    warnings.warn(
+        "QuantNodes.agent loaded without nanobot-ai (NANOBOT_AVAILABLE=False). "
+        "Agent / WebUI / MCP features are disabled. "
+        "Install with:  pip install 'quantnodes[agent]'",
+        ImportWarning,
+        stacklevel=2,
+    )
+
+
+__all__ = [
+    "__version__",
+    "NANOBOT_AVAILABLE",
+    "NANOBOT_IMPORT_ERROR",
+    "NanobotNotInstalled",
+    "Agent",
+    "QuantDreamHook",
+    "QuantDreamInsight",
+    "DreamEngine",
+    "register_all_quant_tools",
+]

QuantNodes/agent/agents/__init__.py

@@ -0,0 +1,13 @@
+# coding=utf-8
+"""
+Agent 多模式模块
+"""
+
+from .definition import AgentDefinition, QUANTNODES_AGENTS
+from .manager import AgentManager
+
+__all__ = [
+    "AgentDefinition",
+    "QUANTNODES_AGENTS",
+    "AgentManager",
+]

QuantNodes/agent/agents/definition.py

@@ -0,0 +1,180 @@
+# coding=utf-8
+"""
+Agent 定义模块
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+from ..permission.models import PermissionRule, Action
+
+
+@dataclass
+class AgentDefinition:
+    """Agent 定义"""
+    id: str
+    name: str
+    description: str
+    mode: str = "primary"
+    permission_rules: list[PermissionRule] = field(default_factory=list)
+    model: Optional[str] = None
+    max_iterations: int = 20
+    temperature: float = 0.7
+    tools_allowed: Optional[set[str]] = None
+    tools_denied: set[str] = field(default_factory=set)
+    system_prompt_override: Optional[str] = None
+
+
+QUANTNODES_AGENTS: Dict[str, AgentDefinition] = {
+    "build": AgentDefinition(
+        id="build",
+        name="Build Agent",
+        description="默认 Agent，具有完整权限，可执行代码修改和分析",
+        mode="primary",
+        permission_rules=[
+            PermissionRule("*", "*", Action.ALLOW),
+            PermissionRule("bash", "*", Action.ASK),
+            PermissionRule("external_directory", "*", Action.ASK),
+            PermissionRule("read", "*.env", Action.ASK),
+            PermissionRule("read", "*.env.*", Action.ASK),
+        ],
+    ),
+
+    "plan": AgentDefinition(
+        id="plan",
+        name="Plan Agent",
+        description="只读分析 Agent，禁止文件修改，用于代码探索和策略分析",
+        mode="primary",
+        permission_rules=[
+            PermissionRule("*", "*", Action.ALLOW),
+            PermissionRule("edit", "*", Action.DENY),
+            PermissionRule("bash", "*", Action.DENY),
+            PermissionRule("write", "*", Action.DENY),
+            PermissionRule("read", "*", Action.ALLOW),
+            PermissionRule("glob", "*", Action.ALLOW),
+            PermissionRule("grep", "*", Action.ALLOW),
+            PermissionRule("code_search", "*", Action.ALLOW),
+        ],
+        tools_denied={"sandbox", "git_ops", "file_ops", "strategy", "backtest"},
+    ),
+
+    "explore": AgentDefinition(
+        id="explore",
+        name="Explore Agent",
+        description="快速代码搜索子 Agent，只读，用于代码库探索",
+        mode="subagent",
+        permission_rules=[
+            PermissionRule("*", "*", Action.DENY),
+            PermissionRule("read", "*", Action.ALLOW),
+            PermissionRule("glob", "*", Action.ALLOW),
+            PermissionRule("grep", "*", Action.ALLOW),
+            PermissionRule("code_search", "*", Action.ALLOW),
+            PermissionRule("webfetch", "*", Action.ALLOW),
+        ],
+        tools_denied={
+            "sandbox", "git_ops", "file_ops", "strategy", "backtest",
+            "pipeline", "factor", "config_backtest", "wiki",
+        },
+    ),
+
+    "backtest": AgentDefinition(
+        id="backtest",
+        name="Backtest Agent",
+        description="回测专用 Agent，专注于策略回测和分析",
+        mode="subagent",
+        permission_rules=[
+            PermissionRule("*", "*", Action.ALLOW),
+            PermissionRule("bash", "*", Action.ASK),
+        ],
+        tools_allowed={
+            "backtest", "config_backtest", "factor", "strategy",
+            "read", "glob", "grep", "code_search", "wiki",
+        },
+    ),
+
+    # ========================================================================
+    # M5 Alpha-GPT 5-subagent 编排 (基于 .agent/agents/alpha-gpt-*.md)
+    # ========================================================================
+
+    "alpha-gpt-idea-generator": AgentDefinition(
+        id="alpha-gpt-idea-generator",
+        name="Alpha-GPT Idea Generator",
+        description=(
+            "Alpha-GPT 第 1 阶段：根据 objective 生成 N 个 alpha 因子想法。"
+            "无工具，纯文本生成。"
+        ),
+        mode="subagent",
+        temperature=0.8,
+        max_iterations=3,
+        tools_denied={
+            "sandbox", "bash", "shell", "edit", "write", "file_ops",
+            "git_ops", "alpha_evaluate", "alpha_backtest",
+            "backtest", "pipeline", "factor", "config_backtest",
+        },
+    ),
+
+    "alpha-gpt-formula-translator": AgentDefinition(
+        id="alpha-gpt-formula-translator",
+        name="Alpha-GPT Formula Translator",
+        description=(
+            "Alpha-GPT 第 2 阶段：把 alpha 想法翻译成 polars 公式。"
+            "无工具，纯文本生成 + 公式白名单校验。"
+        ),
+        mode="subagent",
+        temperature=0.5,
+        max_iterations=3,
+        tools_denied={
+            "sandbox", "bash", "shell", "edit", "write", "file_ops",
+            "git_ops", "alpha_evaluate", "alpha_backtest",
+            "backtest", "pipeline", "factor", "config_backtest",
+        },
+    ),
+
+    "alpha-gpt-evaluator": AgentDefinition(
+        id="alpha-gpt-evaluator",
+        name="Alpha-GPT Evaluator",
+        description=(
+            "Alpha-GPT 第 3 阶段：调 alpha_evaluate / alpha_backtest 工具"
+            "对公式做 IC/IR/Trading 回测评估。"
+        ),
+        mode="subagent",
+        temperature=0.3,
+        max_iterations=5,
+        tools_allowed={
+            "alpha_evaluate", "alpha_backtest", "read", "glob",
+        },
+    ),
+
+    "alpha-gpt-reflector": AgentDefinition(
+        id="alpha-gpt-reflector",
+        name="Alpha-GPT Reflector",
+        description=(
+            "Alpha-GPT 第 4 阶段：基于评估结果反思 keep/mutate/drop，"
+            "给下一轮 IdeaGenerator 改进建议。无工具。"
+        ),
+        mode="subagent",
+        temperature=0.5,
+        max_iterations=3,
+        tools_denied={
+            "sandbox", "bash", "shell", "edit", "write", "file_ops",
+            "git_ops", "alpha_evaluate", "alpha_backtest",
+            "backtest", "pipeline", "factor", "config_backtest",
+        },
+    ),
+
+    "alpha-gpt-critic": AgentDefinition(
+        id="alpha-gpt-critic",
+        name="Alpha-GPT Critic",
+        description=(
+            "Alpha-GPT 第 5 阶段：从所有历史公式中选最终 top-K，"
+            "综合 IR / 衰减 / mutual_IC 评分。无工具。"
+        ),
+        mode="subagent",
+        temperature=0.2,
+        max_iterations=3,
+        tools_denied={
+            "sandbox", "bash", "shell", "edit", "write", "file_ops",
+            "git_ops", "alpha_evaluate", "alpha_backtest",
+            "backtest", "pipeline", "factor", "config_backtest",
+        },
+    ),
+}

QuantNodes/agent/agents/manager.py

@@ -0,0 +1,73 @@
+# coding=utf-8
+"""
+Agent 管理器
+"""
+
+from typing import Dict, Optional
+from .definition import AgentDefinition, QUANTNODES_AGENTS
+from ..permission.service import PermissionService
+from ..permission.defaults import create_default_ruleset
+
+
+class AgentManager:
+    """Agent 管理器
+
+    职责：
+    1. 管理 Agent 定义
+    2. 处理 Agent 切换
+    3. 为每个 Agent 创建权限服务
+    """
+
+    def __init__(self, project_root: str):
+        self._agents = dict(QUANTNODES_AGENTS)
+        self._current_agent: str = "build"
+        self._project_root = project_root
+        self._permission_services: Dict[str, PermissionService] = {}
+
+    def get_current_agent(self) -> AgentDefinition:
+        """获取当前 Agent"""
+        return self._agents[self._current_agent]
+
+    def set_agent(self, agent_id: str) -> AgentDefinition:
+        """切换 Agent
+
+        Args:
+            agent_id: Agent ID
+
+        Returns:
+            新的 Agent 定义
+
+        Raises:
+            ValueError: 如果 Agent 不存在
+        """
+        if agent_id not in self._agents:
+            raise ValueError(f"Agent not found: {agent_id}")
+
+        self._current_agent = agent_id
+        return self._agents[agent_id]
+
+    def get_permission_service(self, agent_id: Optional[str] = None) -> PermissionService:
+        """获取 Agent 的权限服务
+
+        每个 Agent 有独立的权限服务，规则集根据 Agent 定义合并。
+        """
+        agent_id = agent_id or self._current_agent
+
+        if agent_id not in self._permission_services:
+            default_rules = create_default_ruleset(self._project_root)
+            agent_rules = self._agents[agent_id].permission_rules
+            combined_rules = default_rules + agent_rules
+
+            self._permission_services[agent_id] = PermissionService(
+                ruleset=combined_rules,
+            )
+
+        return self._permission_services[agent_id]
+
+    def list_agents(self) -> list[AgentDefinition]:
+        """列出所有 Agent"""
+        return list(self._agents.values())
+
+    def register_agent(self, agent: AgentDefinition) -> None:
+        """注册自定义 Agent"""
+        self._agents[agent.id] = agent

QuantNodes/agent/config/__init__.py

@@ -0,0 +1,34 @@
+# coding=utf-8
+"""
+QuantNodes Agent Config - 配置文件驱动模块
+
+基于 YAML 的策略配置加载和执行。
+
+Modules:
+    types: 类型定义
+    loader: 配置加载器
+    executor: 配置执行器
+
+Usage:
+    from QuantNodes.agent.config import ConfigLoader, ConfigExecutor
+
+    loader = ConfigLoader()
+    config = loader.load("strategy.yaml")
+
+    executor = ConfigExecutor()
+    result = executor.run(config, data)
+"""
+
+from .loader import ConfigLoader, load_config
+from .executor import ConfigExecutor
+from .types import StrategyConfig, FactorConfig, OperationConfig, BacktestConfig
+
+__all__ = [
+    "ConfigLoader",
+    "ConfigExecutor",
+    "load_config",
+    "StrategyConfig",
+    "FactorConfig",
+    "OperationConfig",
+    "BacktestConfig",
+]