quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/knowledge/retriever.py

@@ -0,0 +1,209 @@
+"""Retriever — 因子知识库检索抽象。
+
+抽象:
+    BaseRetriever: interface
+    TFIDFRetriever: 基于 sklearn TfidfVectorizer (默认实现)
+    IdentityRetriever: 无 embedding, 仅按文本匹配 (fallback / 测试)
+"""
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class BaseRetriever(Protocol):
+    """Retriever 协议。
+
+    方法:
+        add(doc_id, text) -> None: 添加文档
+        query(text, top_k) -> list[(doc_id, score)]: 检索 top-k, 降序
+        save(path) / load(path): 可选持久化
+    """
+
+    def add(self, doc_id: str, text: str) -> None: ...
+    def query(self, text: str, top_k: int = 5) -> list[tuple[str, float]]: ...
+
+
+# ============================================================================
+# TFIDFRetriever (sklearn)
+# ============================================================================
+
+class TFIDFRetriever:
+    """基于 sklearn TfidfVectorizer 的稀疏检索器。
+
+    Args:
+        token_pattern: sklearn 分词正则 (默认支持 alnum + 下划线)
+
+    v3.0.0 graceful degradation: if ``sklearn`` is not installed,
+    ``TFIDFRetriever`` falls back to :class:`IdentityRetriever`
+    (pure-Python TF-IDF) instead of raising ``ModuleNotFoundError``.
+    A ``RuntimeWarning`` is emitted so users can install sklearn
+    explicitly: ``pip install scikit-learn``.
+    """
+
+    def __init__(self, token_pattern: str | None = None):
+        try:
+            from sklearn.feature_extraction.text import TfidfVectorizer
+            self._vectorizer = TfidfVectorizer(
+                token_pattern=token_pattern or r"(?u)\b\w+\b",
+                lowercase=True,
+            )
+            self._sklearn = True
+        except ImportError:
+            import warnings
+            warnings.warn(
+                "scikit-learn not installed; TFIDFRetriever falling back to "
+                "IdentityRetriever (pure-Python). Install scikit-learn for "
+                "the full sklearn-backed retrieval: pip install scikit-learn",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+            # Delegate to IdentityRetriever (we'll forward add/query through
+            # the same interface by storing an internal instance)
+            self._fallback = IdentityRetriever()
+            self._sklearn = False
+            self._vectorizer = None
+            self._doc_ids = None  # sentinel; not used in fallback mode
+            self._matrix = None
+            return
+
+        self._doc_ids: list[str] = []
+        self._texts: list[str] = []
+        self._matrix = None  # 懒构建
+
+    def add(self, doc_id: str, text: str) -> None:
+        """添加一条文档, 标记 matrix 失效。"""
+        if not self._sklearn:
+            # Fallback to IdentityRetriever (pure-Python TF-IDF)
+            return self._fallback.add(doc_id, text)
+        if doc_id in self._doc_ids:
+            # 更新: 移除旧的
+            idx = self._doc_ids.index(doc_id)
+            self._doc_ids.pop(idx)
+            self._texts.pop(idx)
+        self._doc_ids.append(doc_id)
+        self._texts.append(text)
+        self._matrix = None
+
+    def _ensure_matrix(self):
+        if self._matrix is None and self._texts:
+            self._matrix = self._vectorizer.fit_transform(self._texts)
+
+    def query(self, text: str, top_k: int = 5) -> list[tuple[str, float]]:
+        """返回 top_k 文档, 列表 [(doc_id, score)] 降序。"""
+        if not self._sklearn:
+            return self._fallback.query(text, top_k)
+        if not self._doc_ids:
+            return []
+        self._ensure_matrix()
+        q_vec = self._vectorizer.transform([text])
+        # cosine = (q · d) / (||q|| * ||d||), TfidfVectorizer 已 L2 normalize
+        scores = (self._matrix @ q_vec.T).toarray().ravel()
+        ranked = sorted(
+            enumerate(scores), key=lambda x: x[1], reverse=True,
+        )[:top_k]
+        return [(self._doc_ids[i], float(s)) for i, s in ranked if s > 0]
+
+    def __len__(self) -> int:
+        if not self._sklearn:
+            return len(self._fallback)
+        return len(self._doc_ids)
+
+
+# ============================================================================
+# IdentityRetriever (纯 Python, 无 sklearn 依赖)
+# ============================================================================
+
+_WORD_RE = re.compile(r"(?u)\b\w+\b")
+
+
+def _tokenize(text: str) -> list[str]:
+    return [t.lower() for t in _WORD_RE.findall(text)]
+
+
+def _compute_idf(docs: list[list[str]]) -> dict[str, float]:
+    """IDF = log(N / df) + 1, 平滑版。"""
+    n = len(docs)
+    df: Counter = Counter()
+    for tokens in docs:
+        for unique in set(tokens):
+            df[unique] += 1
+    return {term: math.log((n + 1) / (df_t + 1)) + 1 for term, df_t in df.items()}
+
+
+class IdentityRetriever:
+    """纯 Python TF-IDF (无 sklearn 依赖), 用于测试和小规模场景。
+
+    实现: 词频 × IDF, cosine 相似度。
+    """
+
+    def __init__(self):
+        self._doc_ids: list[str] = []
+        self._tokenized: list[list[str]] = []
+        self._idf: dict[str, float] = {}
+        self._norms: list[float] = []
+        self._dirty = True
+
+    def add(self, doc_id: str, text: str) -> None:
+        if doc_id in self._doc_ids:
+            idx = self._doc_ids.index(doc_id)
+            self._doc_ids.pop(idx)
+            self._tokenized.pop(idx)
+        self._doc_ids.append(doc_id)
+        self._tokenized.append(_tokenize(text))
+        self._dirty = True
+
+    def _rebuild(self) -> None:
+        self._idf = _compute_idf(self._tokenized)
+        self._norms = []
+        for tokens in self._tokenized:
+            tf = Counter(tokens)
+            vec = {t: (tf[t] / max(len(tokens), 1)) * self._idf.get(t, 0.0)
+                   for t in tokens}
+            self._norms.append(math.sqrt(sum(v * v for v in vec.values())) or 1e-9)
+        self._dirty = False
+
+    def query(self, text: str, top_k: int = 5) -> list[tuple[str, float]]:
+        if not self._doc_ids:
+            return []
+        if self._dirty:
+            self._rebuild()
+        q_tokens = _tokenize(text)
+        q_tf = Counter(q_tokens)
+        q_vec = {t: (q_tf[t] / max(len(q_tokens), 1)) * self._idf.get(t, 0.0)
+                 for t in q_tokens}
+        q_norm = math.sqrt(sum(v * v for v in q_vec.values())) or 1e-9
+        scores: list[tuple[int, float]] = []
+        for i, tokens in enumerate(self._tokenized):
+            tf = Counter(tokens)
+            d_vec = {t: (tf[t] / max(len(tokens), 1)) * self._idf.get(t, 0.0)
+                     for t in tokens}
+            dot = sum(q_vec.get(t, 0) * d_vec.get(t, 0) for t in q_vec)
+            sim = dot / (q_norm * self._norms[i])
+            if sim > 0:
+                scores.append((i, sim))
+        scores.sort(key=lambda x: x[1], reverse=True)
+        return [(self._doc_ids[i], float(s)) for i, s in scores[:top_k]]
+
+    def __len__(self) -> int:
+        return len(self._doc_ids)
+
+
+# ============================================================================
+# Factory
+# ============================================================================
+
+def make_retriever(kind: str = "tfidf") -> BaseRetriever:
+    """构造 retriever。
+
+    Args:
+        kind: "tfidf" (sklearn, 优先) / "identity" (纯 Python)
+    """
+    if kind == "tfidf":
+        return TFIDFRetriever()
+    if kind == "identity":
+        return IdentityRetriever()
+    raise ValueError(f"未知 retriever kind: {kind!r}")

QuantNodes/core/lambda_node.py

@@ -0,0 +1,81 @@
+# coding=utf-8
+"""
+LambdaNode 便捷节点类
+
+用于快速将函数包装为节点，适合简单的转换逻辑。
+"""
+
+from typing import Any, Callable, Dict
+from QuantNodes.core.node import BaseNode, SerializationError
+from QuantNodes.core.serializable import serializable
+
+
+@serializable
+class LambdaNode(BaseNode):
+    """
+    将函数包装为节点
+
+    Examples:
+        >>> # 简单函数
+        >>> add_one = LambdaNode(lambda x: x + 1)
+        >>> add_one.execute(5)  # 6
+        >>>
+        >>> # 更复杂的逻辑
+        >>> rolling_mean = LambdaNode(
+        ...     lambda df, ctx: df.rolling(ctx.config['window']).mean(),
+        ...     config={'window': 20}
+        ... )
+    """
+
+    def __init__(
+        self, func: Callable[[Any, Any], Any], name: str = None,
+        config: Dict[str, Any] = None,
+    ):
+        """
+        Args:
+            func: 执行函数，签名为 func(input_data, context) -> result
+            name: 节点名称，默认为函数名
+            config: 配置字典
+        """
+        self.func = func
+        name = name or (func.__name__ if hasattr(func, '__name__') else 'Lambda')
+        super().__init__(name=name, config=config)
+
+    def _execute(self, input_data: Any = None, **kwargs) -> Any:
+        return self.func(input_data, self)
+
+    def _get_serializable_fields(self) -> Dict[str, Any]:
+        """返回需要序列化的额外字段"""
+        func = self.func
+
+        if hasattr(func, "__name__") and func.__name__ == "<lambda>":
+            raise SerializationError(
+                "LambdaNode with anonymous lambda cannot be serialized. "
+                "Please use a named function instead."
+            )
+
+        return {
+            "func": {
+                "type": "named_function",
+                "module": func.__module__,
+                "qualname": func.__qualname__
+            }
+        }
+
+    @classmethod
+    def _from_dict_impl(cls, data: Dict[str, Any]) -> 'LambdaNode':
+        """从字典反序列化重建 LambdaNode"""
+        import importlib
+
+        func_info = data["func"]
+        if func_info["type"] != "named_function":
+            raise ValueError(f"Unsupported function type: {func_info['type']}")
+
+        module = importlib.import_module(func_info["module"])
+        func = getattr(module, func_info["qualname"])
+
+        return LambdaNode(
+            func=func,
+            name=data.get("name"),
+            config=data.get("config", {})
+        )

QuantNodes/core/monitoring/__init__.py

@@ -0,0 +1,22 @@
+"""Monitoring — 3 类指标中央收集 + Plotly dashboard。
+
+公开 API:
+    - RagMetrics / EvolutionMetrics / QualityMetrics (数据类)
+    - MetricCollector (中央收集器)
+    - generate_dashboard_html (HTML 报告)
+"""
+from .collector import (
+    EvolutionMetrics,
+    MetricCollector,
+    QualityMetrics,
+    RagMetrics,
+)
+from .dashboard import generate_dashboard_html
+
+__all__ = [
+    "RagMetrics",
+    "EvolutionMetrics",
+    "QualityMetrics",
+    "MetricCollector",
+    "generate_dashboard_html",
+]

QuantNodes/core/monitoring/collector.py

@@ -0,0 +1,292 @@
+"""MetricCollector — 3 类指标的中央收集器。
+
+3 类指标:
+    - RAG:    HitRate@K / NDCG@K / MRR / Diversity (per-round)
+    - Evo:    pool_size / total_count / rejected_count / best_sharpe
+    - Quality: 各 QualityGate 通道 pass/fail (per-round)
+
+数据来源:
+    - RAG: EvolutionLoop.rag_metrics_history
+    - Evo: TrajectoryPool + EvolutionResult
+    - Quality: TrajectoryEntry.feedback.channels
+
+数据流:
+    演化 → MetricCollector.update(loop_result) → 3 类指标 append → JSON / Dashboard
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+import pandas as pd
+
+from ..feedback import FeedbackChannel
+from ..trajectory import TrajectoryPool
+from QuantNodes.core.path_utils import ensure_parent
+
+
+# ============================================================================
+# 数据类
+# ============================================================================
+
+@dataclass
+class RagMetrics:
+    """单轮 RAG 评估指标 (Week 10)。
+
+    字段命名包含 K (5/10) 是历史设计, 为保持序列化兼容保留。
+    自定义 K (如 K=3, K=20) 通过 `extra: dict[str, float]` 扩展,
+    避免 dataclass 字段爆炸。
+    """
+    round: int
+    n_queries: int
+    hit_at_5: float = 0.0
+    hit_at_10: float = 0.0
+    ndcg_at_5: float = 0.0
+    ndcg_at_10: float = 0.0
+    mrr: float = 0.0
+    lineage_coverage: float = 0.0
+    diversity: float = 0.0
+    extra: dict[str, float] = field(default_factory=dict)
+    timestamp: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now().isoformat()
+
+    def get(self, key: str, default: float = 0.0) -> float:
+        """统一访问入口: 优先 `extra`, 回退命名字段 (兼容 hit_at_5 形式)。"""
+        if key in self.extra:
+            return self.extra[key]
+        return getattr(self, key, default)
+
+
+@dataclass
+class EvolutionMetrics:
+    """单轮演化统计。"""
+    round: int
+    pool_size: int = 0
+    total_count: int = 0
+    rejected_count: int = 0
+    best_metric: float = 0.0
+    best_factor_name: str = ""
+    timestamp: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now().isoformat()
+
+
+@dataclass
+class QualityMetrics:
+    """单轮 Quality Gate 通道统计。"""
+    round: int
+    code_pass: int = 0
+    code_fail: int = 0
+    value_pass: int = 0
+    value_fail: int = 0
+    llm_pass: int = 0
+    llm_fail: int = 0
+    timestamp: str = ""
+
+    def __post_init__(self):
+        if not self.timestamp:
+            self.timestamp = datetime.now().isoformat()
+
+
+# ============================================================================
+# MetricCollector
+# ============================================================================
+
+class MetricCollector:
+    """3 类指标中央收集器。
+
+    用法:
+        collector = MetricCollector()
+        collector.update_from_loop(loop, result)
+        collector.update_quality_from_pool(pool, round_idx=N)
+        collector.save(Path("metrics.json"))
+    """
+
+    def __init__(self):
+        self.rag_history: list[RagMetrics] = []
+        self.evolution_history: list[EvolutionMetrics] = []
+        self.quality_history: list[QualityMetrics] = []
+
+    # ------------------------------------------------------------------
+    # RAG 指标
+    # ------------------------------------------------------------------
+
+    def add_rag(self, metrics: RagMetrics) -> None:
+        """添加 1 轮 RAG 指标。"""
+        self.rag_history.append(metrics)
+
+    def update_from_loop(self, loop, result) -> None:
+        """从 EvolutionLoop.rag_metrics_history 提取 RAG 指标。"""
+        for m in loop.rag_metrics_history:
+            self.add_rag(RagMetrics(
+                round=m.get("round", 0),
+                n_queries=m.get("n_queries", 0),
+                hit_at_5=m.get("hit_at_5", 0.0),
+                hit_at_10=m.get("hit_at_10", 0.0),
+                ndcg_at_5=m.get("ndcg_at_5", 0.0),
+                ndcg_at_10=m.get("ndcg_at_10", 0.0),
+                mrr=m.get("mrr", 0.0),
+                lineage_coverage=m.get("lineage_coverage", 0.0),
+                diversity=m.get("diversity", 0.0),
+            ))
+        # 添加最终演化统计
+        self.add_evolution(EvolutionMetrics(
+            round=result.rounds_completed,
+            pool_size=result.total_count + result.rejected_count,
+            total_count=result.total_count,
+            rejected_count=result.rejected_count,
+            best_metric=(
+                result.best_entries[0].metrics.get("sharpe", 0.0)
+                if result.best_entries else 0.0
+            ),
+            best_factor_name=(
+                result.best_entries[0].feedback.factor_name
+                if result.best_entries and result.best_entries[0].feedback
+                else ""
+            ),
+        ))
+
+    # ------------------------------------------------------------------
+    # 演化统计
+    # ------------------------------------------------------------------
+
+    def add_evolution(self, metrics: EvolutionMetrics) -> None:
+        self.evolution_history.append(metrics)
+
+    def update_evolution_from_pool(
+        self, pool: TrajectoryPool, round_idx: int = 0,
+        metric: str = "sharpe",  # M4: 监控指标可调 (默认 sharpe)
+    ) -> None:
+        """从 TrajectoryPool 提取当前统计。"""
+        passed = sum(1 for e in pool.all() if e.feedback and e.feedback.decision)
+        rejected = pool.size - passed
+        best_val = 0.0
+        best_name = ""
+        for e in pool.all():
+            val = (e.metrics or {}).get(metric, 0)
+            if val > best_val:
+                best_val = val
+                if e.feedback:
+                    best_name = e.feedback.factor_name
+        self.add_evolution(EvolutionMetrics(
+            round=round_idx, pool_size=pool.size,
+            total_count=passed, rejected_count=rejected,
+            best_metric=best_val, best_factor_name=best_name,
+        ))
+
+    # ------------------------------------------------------------------
+    # Quality Gate 通道统计
+    # ------------------------------------------------------------------
+
+    def add_quality(self, metrics: QualityMetrics) -> None:
+        self.quality_history.append(metrics)
+
+    def update_quality_from_pool(
+        self, pool: TrajectoryPool, round_idx: int = 0,
+    ) -> None:
+        """从 pool 中 round_idx 过滤, 统计每通道 pass/fail。"""
+        code_pass = code_fail = value_pass = value_fail = llm_pass = llm_fail = 0
+        for e in pool.all():
+            if e.round_idx != round_idx:
+                continue
+            if not e.feedback or not e.feedback.channels:
+                continue
+            for ch, fb in e.feedback.channels.items():
+                passed = fb.passed
+                if ch == FeedbackChannel.CODE:
+                    code_pass += int(passed)
+                    code_fail += int(not passed)
+                elif ch == FeedbackChannel.VALUE:
+                    value_pass += int(passed)
+                    value_fail += int(not passed)
+                elif ch == FeedbackChannel.LLM:
+                    llm_pass += int(passed)
+                    llm_fail += int(not passed)
+        self.add_quality(QualityMetrics(
+            round=round_idx,
+            code_pass=code_pass, code_fail=code_fail,
+            value_pass=value_pass, value_fail=value_fail,
+            llm_pass=llm_pass, llm_fail=llm_fail,
+        ))
+
+    # ------------------------------------------------------------------
+    # 序列化
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        return {
+            "rag": [asdict(m) for m in self.rag_history],
+            "evolution": [asdict(m) for m in self.evolution_history],
+            "quality": [asdict(m) for m in self.quality_history],
+            "generated_at": datetime.now().isoformat(),
+        }
+
+    def save(self, path: Path | str) -> None:
+        """保存为 JSON。"""
+        path = Path(path)
+        ensure_parent(path)
+        with path.open("w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, ensure_ascii=False, indent=2)
+
+    @classmethod
+    def load(cls, path: Path | str) -> "MetricCollector":
+        """从 JSON 加载。"""
+        path = Path(path)
+        if not path.exists():
+            return cls()
+        data = json.loads(path.read_text(encoding="utf-8"))
+        c = cls()
+        for m in data.get("rag", []):
+            c.rag_history.append(RagMetrics(**m))
+        for m in data.get("evolution", []):
+            c.evolution_history.append(EvolutionMetrics(**m))
+        for m in data.get("quality", []):
+            c.quality_history.append(QualityMetrics(**m))
+        return c
+
+    def append_json(self, path: Path | str) -> None:
+        """追加写入 JSON (streaming 模式: 读旧数据 → 追加 → 写回)。
+
+        读已有文件 → 合并 → 写回, 支持多轮逐步写入。
+        """
+        path = Path(path)
+        existing = self.load(path) if path.exists() else MetricCollector()
+        # 合并: 保留已有的, 追加新的 (跳过已存在的 round)
+        existing_rounds = {m.round for m in existing.rag_history}
+        for m in self.rag_history:
+            if m.round not in existing_rounds:
+                existing.rag_history.append(m)
+        evo_existing = {m.round for m in existing.evolution_history}
+        for m in self.evolution_history:
+            if m.round not in evo_existing:
+                existing.evolution_history.append(m)
+        qg_existing = {m.round for m in existing.quality_history}
+        for m in self.quality_history:
+            if m.round not in qg_existing:
+                existing.quality_history.append(m)
+        existing.save(path)
+
+    def save_csv(self, path_prefix: Path | str) -> None:
+        """保存 3 类指标为 3 个 CSV。"""
+        path_prefix = Path(path_prefix)
+        ensure_parent(path_prefix)
+        for name, history in (
+            ("rag", self.rag_history),
+            ("evolution", self.evolution_history),
+            ("quality", self.quality_history),
+        ):
+            if history:
+                pd.DataFrame([asdict(m) for m in history]).to_csv(
+                    path_prefix.with_name(f"{path_prefix.name}_{name}.csv"),
+                    index=False,
+                )
+
+    def __len__(self) -> int:
+        return len(self.rag_history) + len(self.evolution_history) + len(self.quality_history)