quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/providers/rate_limiter.py

@@ -0,0 +1,326 @@
+# coding=utf-8
+"""
+速率限制模块 (Rate Limiter)
+
+提供 Token Bucket 算法实现，用于控制 LLM API 请求频率。
+解决 OpenRouter 免费账号的严格速率限制问题（每天 50 次请求）。
+"""
+
+import time
+import asyncio
+import threading
+
+
+class TokenBucket:
+    """同步令牌桶速率限制器
+
+    用于多线程环境下的请求频率控制。
+
+    Args:
+        requests_per_second: 每秒允许的请求数（免费账号建议 0.5）
+        burst: 突发容量，允许的最大突发请求数
+    """
+
+    def __init__(self, requests_per_second: float = 0.5, burst: int = 1):
+        """
+        Args:
+            requests_per_second: 每秒允许的请求数，默认 0.5 即每2秒1次请求
+            burst: 突发容量，默认 1 表示每次最多处理1个请求
+        """
+        if requests_per_second <= 0:
+            raise ValueError("requests_per_second must be positive")
+        if burst < 1:
+            raise ValueError("burst must be at least 1")
+
+        self.rate = requests_per_second
+        self.burst = burst
+        self.tokens = float(burst)
+        self.last_update = time.time()
+        self.lock = threading.Lock()
+
+    def _refill(self) -> None:
+        """补充令牌"""
+        now = time.time()
+        elapsed = now - self.last_update
+        self.tokens = min(self.burst, self.tokens + elapsed * self.rate)
+        self.last_update = now
+
+    def acquire(self, blocking: bool = True) -> bool:
+        """获取令牌
+
+        Args:
+            blocking: 是否阻塞等待令牌可用
+
+        Returns:
+            True if token acquired, False if not (non-blocking mode only)
+        """
+        with self.lock:
+            self._refill()
+
+            if self.tokens >= 1:
+                self.tokens -= 1
+                return True
+
+            if not blocking:
+                return False
+
+            wait_time = (1 - self.tokens) / self.rate
+            time.sleep(wait_time)
+            self.tokens = 0
+            return True
+
+    def try_acquire(self) -> bool:
+        """非阻塞尝试获取令牌"""
+        return self.acquire(blocking=False)
+
+    @property
+    def available_tokens(self) -> float:
+        """当前可用令牌数"""
+        with self.lock:
+            self._refill()
+            return self.tokens
+
+
+class AsyncTokenBucket:
+    """异步令牌桶速率限制器
+
+    用于 asyncio 环境下的请求频率控制。
+
+    Args:
+        requests_per_second: 每秒允许的请求数（免费账号建议 0.5）
+        burst: 突发容量
+    """
+
+    def __init__(self, requests_per_second: float = 0.5, burst: int = 1):
+        """
+        Args:
+            requests_per_second: 每秒允许的请求数，默认 0.5 即每2秒1次请求
+            burst: 突发容量，默认 1
+        """
+        if requests_per_second <= 0:
+            raise ValueError("requests_per_second must be positive")
+        if burst < 1:
+            raise ValueError("burst must be at least 1")
+
+        self.rate = requests_per_second
+        self.burst = burst
+        self.tokens = float(burst)
+        self.last_update = time.time()
+        self.lock = asyncio.Lock()
+
+    async def _refill(self) -> None:
+        """补充令牌"""
+        now = time.time()
+        elapsed = now - self.last_update
+        self.tokens = min(self.burst, self.tokens + elapsed * self.rate)
+        self.last_update = now
+
+    async def acquire(self) -> None:
+        """获取令牌，必要时等待
+
+        这是阻塞方法，会等待直到令牌可用。
+        """
+        async with self.lock:
+            await self._refill()
+
+            if self.tokens >= 1:
+                self.tokens -= 1
+                return
+
+            wait_time = (1 - self.tokens) / self.rate
+            await asyncio.sleep(wait_time)
+            self.tokens = 0
+
+    async def try_acquire(self) -> bool:
+        """非阻塞尝试获取令牌
+
+        Returns:
+            True if token acquired, False otherwise
+        """
+        async with self.lock:
+            await self._refill()
+
+            if self.tokens >= 1:
+                self.tokens -= 1
+                return True
+
+            return False
+
+    async def wait_time(self) -> float:
+        """计算获取令牌需要等待的时间
+
+        Returns:
+            等待时间（秒），如果立即可用则返回 0
+        """
+        async with self.lock:
+            await self._refill()
+
+            if self.tokens >= 1:
+                return 0.0
+
+            return (1 - self.tokens) / self.rate
+
+    @property
+    def available_tokens(self) -> float:
+        """当前可用令牌数（非线程安全，仅供调试）"""
+        return self.tokens
+
+
+class SlidingWindowRateLimiter:
+    """滑动窗口速率限制器
+
+    另一种速率限制实现，在固定时间窗口内限制请求数。
+
+    Args:
+        max_requests: 时间窗口内最大请求数
+        window_seconds: 时间窗口长度（秒）
+    """
+
+    def __init__(self, max_requests: int = 10, window_seconds: float = 60.0):
+        if max_requests <= 0:
+            raise ValueError("max_requests must be positive")
+        if window_seconds <= 0:
+            raise ValueError("window_seconds must be positive")
+
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests: list[float] = []
+        self.lock = threading.Lock()
+
+    def _clean_old_requests(self) -> None:
+        """清除过期请求记录"""
+        now = time.time()
+        cutoff = now - self.window_seconds
+        self.requests = [t for t in self.requests if t > cutoff]
+
+    def acquire(self, blocking: bool = True) -> bool:
+        """获取许可"""
+        with self.lock:
+            self._clean_old_requests()
+
+            if len(self.requests) < self.max_requests:
+                self.requests.append(time.time())
+                return True
+
+            if not blocking:
+                return False
+
+            oldest = self.requests[0]
+            wait_time = oldest + self.window_seconds - time.time()
+            if wait_time > 0:
+                time.sleep(wait_time)
+
+            self._clean_old_requests()
+            self.requests.append(time.time())
+            return True
+
+    def try_acquire(self) -> bool:
+        """非阻塞尝试获取许可"""
+        return self.acquire(blocking=False)
+
+
+class AsyncSlidingWindowRateLimiter:
+    """异步滑动窗口速率限制器"""
+
+    def __init__(self, max_requests: int = 10, window_seconds: float = 60.0):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self.requests: list[float] = []
+        self.lock = asyncio.Lock()
+
+    async def _clean_old_requests(self) -> None:
+        """清除过期请求记录"""
+        now = time.time()
+        cutoff = now - self.window_seconds
+        self.requests = [t for t in self.requests if t > cutoff]
+
+    async def acquire(self) -> None:
+        """获取许可"""
+        async with self.lock:
+            await self._clean_old_requests()
+
+            if len(self.requests) < self.max_requests:
+                self.requests.append(time.time())
+                return
+
+            oldest = self.requests[0]
+            wait_time = oldest + self.window_seconds - time.time()
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+
+            await self._clean_old_requests()
+            self.requests.append(time.time())
+
+    async def try_acquire(self) -> bool:
+        """非阻塞尝试获取许可"""
+        async with self.lock:
+            await self._clean_old_requests()
+
+            if len(self.requests) < self.max_requests:
+                self.requests.append(time.time())
+                return True
+
+            return False
+
+
+class AdaptiveRateLimiter:
+    """自适应速率限制器
+
+    根据 API 响应自动调整请求速率。
+    当检测到限流错误时自动降低速率，正常时逐步提升。
+
+    Args:
+        initial_rps: 初始速率（每秒请求数）
+        min_rps: 最小速率
+        max_rps: 最大速率
+        increase_factor: 正常时速率增加因子
+        decrease_factor: 触发限流时速率降低因子
+    """
+
+    def __init__(
+        self,
+        initial_rps: float = 0.5,
+        min_rps: float = 0.1,
+        max_rps: float = 2.0,
+        increase_factor: float = 1.1,
+        decrease_factor: float = 0.5,
+    ):
+        self.current_rps = initial_rps
+        self.min_rps = min_rps
+        self.max_rps = max_rps
+        self.increase_factor = increase_factor
+        self.decrease_factor = decrease_factor
+        self.last_adjust_time = time.time()
+        self.lock = threading.Lock()
+
+        self._bucket = TokenBucket(initial_rps, burst=1)
+
+    def report_success(self) -> None:
+        """报告成功调用，适当提高速率"""
+        with self.lock:
+            now = time.time()
+            if now - self.last_adjust_time >= 1.0:
+                self.current_rps = min(self.max_rps, self.current_rps * self.increase_factor)
+                self._bucket = TokenBucket(self.current_rps, burst=1)
+                self.last_adjust_time = now
+
+    def report_rate_limit(self) -> None:
+        """报告限流错误，大幅降低速率"""
+        with self.lock:
+            self.current_rps = max(self.min_rps, self.current_rps * self.decrease_factor)
+            self._bucket = TokenBucket(self.current_rps, burst=1)
+
+    def report_server_error(self) -> None:
+        """报告服务器错误，中等降低速率"""
+        with self.lock:
+            self.current_rps = max(self.min_rps, self.current_rps * 0.7)
+            self._bucket = TokenBucket(self.current_rps, burst=1)
+
+    def acquire(self, blocking: bool = True) -> bool:
+        """获取令牌"""
+        return self._bucket.acquire(blocking)
+
+    @property
+    def current_rate(self) -> float:
+        """当前速率"""
+        return self.current_rps

QuantNodes/agent/providers/registry.py

@@ -0,0 +1,163 @@
+# coding=utf-8
+"""
+Provider 注册表
+
+管理多 LLM Provider 配置，按 model 名路由到正确的 provider。
+支持优先级排序和 fallback 机制。
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProviderConfig:
+    """单个 Provider 配置"""
+    name: str
+    api_key: str
+    api_base: str
+    models: List[str] = field(default_factory=list)
+    extra_headers: Dict[str, str] = field(default_factory=dict)
+    priority: int = 1
+    timeout: int = 60
+    max_retries: int = 3
+
+
+class ProviderRegistry:
+    """Provider 注册表 — 管理多 Provider 配置，按 model 路由"""
+
+    def __init__(self):
+        self._providers: Dict[str, ProviderConfig] = {}
+        self._default_provider: Optional[str] = None
+
+    @classmethod
+    def from_settings(cls, agent_config: dict) -> "ProviderRegistry":
+        """从 settings.json 的 agent 节点加载
+
+        支持两种模式：
+        1. 新模式：agent.providers 字典配置多 provider
+        2. 旧模式：agent.api_key + agent.api_base 单 provider（向后兼容）
+        """
+        registry = cls()
+        providers_data = agent_config.get("providers", {})
+
+        for name, pconfig in providers_data.items():
+            registry.register(ProviderConfig(
+                name=name,
+                api_key=pconfig.get("api_key", ""),
+                api_base=pconfig.get("api_base", ""),
+                models=pconfig.get("models", []),
+                extra_headers=pconfig.get("extra_headers", {}),
+                priority=pconfig.get("priority", 1),
+                timeout=pconfig.get("timeout", 60),
+                max_retries=pconfig.get("max_retries", 3),
+            ))
+
+        registry._default_provider = agent_config.get("provider")
+
+        # 向后兼容：无 providers 配置时，用顶层字段创建单 provider
+        if not providers_data and agent_config.get("api_key"):
+            default_name = registry._default_provider or "default"
+            model = agent_config.get("model", "")
+            registry.register(ProviderConfig(
+                name=default_name,
+                api_key=agent_config.get("api_key", ""),
+                api_base=agent_config.get("api_base", ""),
+                models=[model] if model else [],
+                priority=1,
+                timeout=agent_config.get("llm_timeout", 60),
+                max_retries=agent_config.get("llm_max_retries", 3),
+            ))
+            registry._default_provider = default_name
+
+        return registry
+
+    def register(self, config: ProviderConfig) -> None:
+        """注册一个 Provider"""
+        self._providers[config.name] = config
+
+    def get(self, name: str) -> Optional[ProviderConfig]:
+        """获取指定名称的 Provider"""
+        return self._providers.get(name)
+
+    def resolve(self, model: Optional[str] = None) -> Optional[ProviderConfig]:
+        """根据 model 名找到最优 provider
+
+        路由逻辑：
+        1. model=None → 返回默认 provider
+        2. 默认 provider 的 models 中匹配 → 优先返回
+        3. 所有 provider 中匹配 → 按 priority 排序（数字小优先）
+        4. 都找不到 → 返回默认 provider 兜底
+        """
+        if not self._providers:
+            return None
+
+        # 1. model=None → 默认 provider
+        if model is None:
+            return self._get_default_or_first()
+
+        # 2. 默认 provider 优先
+        default = self._providers.get(self._default_provider)
+        if default and model in default.models:
+            return default
+
+        # 3. 所有 provider 中按 priority 排序
+        candidates = [
+            p for p in self._providers.values()
+            if model in p.models
+        ]
+        if candidates:
+            candidates.sort(key=lambda p: p.priority)
+            return candidates[0]
+
+        # 4. 兜底：返回默认 provider
+        return self._get_default_or_first()
+
+    def _get_default_or_first(self) -> Optional[ProviderConfig]:
+        """获取默认 provider，无默认则返回第一个"""
+        default = self._providers.get(self._default_provider)
+        if default:
+            return default
+        if self._providers:
+            return next(iter(self._providers.values()))
+        return None
+
+    def list_providers(self) -> List[ProviderConfig]:
+        """列出所有已注册的 Provider"""
+        return list(self._providers.values())
+
+    def get_models_map(self) -> Dict[str, List[str]]:
+        """获取 provider → models 映射"""
+        return {
+            name: config.models
+            for name, config in self._providers.items()
+        }
+
+    def get_client(self, config: ProviderConfig):
+        """为指定 provider 创建 OpenAIClient"""
+        from QuantNodes.ai.llm.openai import OpenAIClient
+        return OpenAIClient(
+            api_key=config.api_key,
+            base_url=config.api_base,
+            timeout=config.timeout,
+            max_retries=config.max_retries,
+            extra_headers=config.extra_headers,
+        )
+
+    def get_default_client(self):
+        """获取默认 provider 的 client"""
+        config = self._get_default_or_first()
+        if config:
+            return self.get_client(config)
+        return None
+
+    @property
+    def default_provider_name(self) -> Optional[str]:
+        return self._default_provider
+
+    def __repr__(self) -> str:
+        providers_str = ", ".join(self._providers.keys())
+        return f"ProviderRegistry(default={self._default_provider}, providers=[{providers_str}])"

QuantNodes/agent/skills/__init__.py

@@ -0,0 +1,20 @@
+# coding=utf-8
+"""
+Skill System - Phase 4.1
+
+Skills: Strategy skills, Factor skills, Dream system
+"""
+
+from .base import Skill, SkillCategory, SkillStatus, SkillMetadata, SkillResult
+from .registry import SkillRegistry
+from .loader import SkillLoader
+
+__all__ = [
+    "Skill",
+    "SkillCategory",
+    "SkillStatus",
+    "SkillMetadata",
+    "SkillResult",
+    "SkillRegistry",
+    "SkillLoader",
+]

QuantNodes/agent/skills/base.py

@@ -0,0 +1,118 @@
+# coding=utf-8
+"""
+Skill System Base Classes
+
+Phase 4.1: Skill Infrastructure
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+from datetime import datetime
+from enum import Enum
+
+
+class SkillCategory(Enum):
+    STRATEGY = "strategy"
+    FACTOR = "factor"
+    ANALYSIS = "analysis"
+    DREAM = "dream"
+
+
+class SkillStatus(Enum):
+    ACTIVE = "active"
+    DEPRECATED = "deprecated"
+    EXPERIMENTAL = "experimental"
+
+
+@dataclass
+class SkillMetadata:
+    name: str
+    description: str
+    category: SkillCategory
+    version: str = "1.0"
+    author: str = ""
+    tags: List[str] = field(default_factory=list)
+    examples: List[str] = field(default_factory=list)
+    dependencies: List[str] = field(default_factory=list)
+    status: SkillStatus = SkillStatus.ACTIVE
+    created_at: str = ""
+    updated_at: str = ""
+
+    def __post_init__(self):
+        if not self.created_at:
+            self.created_at = datetime.now().isoformat()
+        if not self.updated_at:
+            self.updated_at = self.created_at
+
+
+@dataclass
+class SkillResult:
+    success: bool
+    data: Any = None
+    error: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    execution_time_ms: float = 0.0
+
+    def to_dict(self) -> Dict:
+        return {
+            "success": self.success,
+            "data": self.data,
+            "error": self.error,
+            "metadata": self.metadata,
+            "execution_time_ms": self.execution_time_ms,
+        }
+
+
+class Skill(ABC):
+    """Skill Abstract Base Class"""
+
+    def __init__(self):
+        self._metadata: Optional[SkillMetadata] = None
+
+    @property
+    @abstractmethod
+    def metadata(self) -> SkillMetadata:
+        """Return skill metadata"""
+        pass
+
+    @property
+    def name(self) -> str:
+        return self.metadata.name
+
+    @property
+    def description(self) -> str:
+        return self.metadata.description
+
+    @property
+    def category(self) -> SkillCategory:
+        return self.metadata.category
+
+    @abstractmethod
+    async def execute(self, context: Dict[str, Any]) -> SkillResult:
+        """Execute the skill"""
+        pass
+
+    def validate_context(
+        self, context: Dict[str, Any], required_keys: List[str]
+    ) -> bool:
+        """Validate if context contains required keys"""
+        return all(k in context for k in required_keys)
+
+    def get_example_prompts(self) -> List[str]:
+        """Return example prompts"""
+        return self.metadata.examples
+
+    def to_tool_schema(self) -> Dict[str, Any]:
+        """Convert to nanobot Tool Schema"""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.get_parameters_schema(),
+            "category": self.category.value,
+        }
+
+    @abstractmethod
+    def get_parameters_schema(self) -> Dict[str, Any]:
+        """Return parameter Schema"""
+        pass

QuantNodes/agent/skills/bridge.py

@@ -0,0 +1,73 @@
+# coding=utf-8
+"""
+Skill → Tool Bridge
+
+将 Skill 自动转换为 Agent Tool 并注册到 ToolRegistry。
+"""
+
+import logging
+from typing import Any, Dict
+
+from ..skills.base import Skill, SkillResult
+from ..skills.registry import SkillRegistry
+from ..tools.base import Tool
+from ..tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class SkillToolAdapter(Tool):
+    """将 Skill 适配为 Tool 接口"""
+
+    def __init__(self, skill: Skill):
+        self._skill = skill
+
+    @property
+    def name(self) -> str:
+        return f"skill_{self._skill.metadata.name}"
+
+    @property
+    def description(self) -> str:
+        return self._skill.metadata.description
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return self._skill.get_parameters_schema()
+
+    @property
+    def read_only(self) -> bool:
+        return True
+
+    async def execute(self, **kwargs: Any) -> Any:
+        try:
+            result: SkillResult = await self._skill.execute(kwargs)
+            return result.to_dict()
+        except Exception as e:
+            logger.error("Skill %s execution failed: %s", self._skill.name, e)
+            return {"success": False, "error": str(e), "data": None}
+
+
+class SkillToolBridge:
+    """将 SkillRegistry 中的 Skill 注册为 Agent Tool"""
+
+    def __init__(self, skill_registry: SkillRegistry, tool_registry: ToolRegistry):
+        self.skill_registry = skill_registry
+        self.tool_registry = tool_registry
+
+    def register_all(self) -> int:
+        """将所有 Skill 注册为 Tool，返回注册数量"""
+        count = 0
+        for skill in self.skill_registry.list_all():
+            tool = SkillToolAdapter(skill)
+            self.tool_registry.register(tool)
+            count += 1
+        return count
+
+    def unregister_all(self) -> int:
+        """移除所有 SkillToolAdapter"""
+        count = 0
+        for tool in list(self.tool_registry.list_tools()):
+            if isinstance(tool, SkillToolAdapter):
+                self.tool_registry.unregister(tool.name)
+                count += 1
+        return count