quantnodes 3.0.0__py3-none-any.whl

QuantNodes/core/visualization/gate_breakdown.py

@@ -0,0 +1,140 @@
+"""Quality Gate 拦截率柱状图 — Plotly bar chart."""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Mapping
+
+# v3.0.0 graceful degradation: if plotly is not installed, the figure
+# functions return None. The HTML generators downstream skip None
+# figures with a friendly install hint.
+try:
+    import plotly.graph_objects as _PLOTLY_GO
+except ImportError:
+    _PLOTLY_GO = None
+
+    import warnings
+    warnings.warn(
+        "plotly not installed; visualization figures will be skipped. "
+        "Install plotly for full rendering: pip install plotly",
+        ImportWarning,
+        stacklevel=1,
+    )
+
+
+
+def gate_breakdown_figure(
+    entries,
+    title: str | None = None,
+) -> Any:
+    """统计每种 quality gate 通道的拦截率, 生成柱状图。
+
+    拦截定义: feedback.decision = False (任一通道失败)
+    按 channel 细分: CODE / VALUE / LLM (来自 FactorFeedback.channels)
+
+    Args:
+        entries: TrajectoryEntry 列表
+        title: 标题
+
+    Returns:
+        plotly.graph_objects.Figure, or None if plotly is not installed.
+    """
+    if _PLOTLY_GO is None:
+        return None
+    go = _PLOTLY_GO
+
+    items = list(entries.values() if isinstance(entries, Mapping) else entries)
+    if not items:
+        fig = go.Figure()
+        fig.update_layout(title="空 pool")
+        return fig
+
+    # 统计每通道 pass / fail
+    from ..feedback import FeedbackChannel
+    channel_stats: dict[str, dict[str, int]] = {
+        ch.value: {"pass": 0, "fail": 0} for ch in FeedbackChannel
+    }
+    for e in items:
+        if not e.feedback or not e.feedback.channels:
+            continue
+        for ch, fb in e.feedback.channels.items():
+            key = ch.value
+            if key not in channel_stats:
+                continue
+            if fb.passed:
+                channel_stats[key]["pass"] += 1
+            else:
+                channel_stats[key]["fail"] += 1
+
+    channels = sorted(channel_stats.keys())
+    pass_counts = [channel_stats[ch]["pass"] for ch in channels]
+    fail_counts = [channel_stats[ch]["fail"] for ch in channels]
+
+    fig = go.Figure()
+    fig.add_trace(go.Bar(
+        x=channels, y=pass_counts,
+        name="pass", marker_color="#54A24B",
+        hovertemplate="%{x}<br>pass=%{y}<extra></extra>",
+    ))
+    fig.add_trace(go.Bar(
+        x=channels, y=fail_counts,
+        name="fail", marker_color="#E45756",
+        hovertemplate="%{x}<br>fail=%{y}<extra></extra>",
+    ))
+
+    fig.update_layout(
+        title=title or "Quality Gate 拦截率 (按通道)",
+        barmode="stack",
+        xaxis_title="channel",
+        yaxis_title="count",
+        height=400,
+        plot_bgcolor="white",
+    )
+    return fig
+
+
+def operation_breakdown_figure(
+    entries,
+    title: str | None = None,
+) -> Any:
+    """按 operation 分类的成功率柱状图。"""
+    if _PLOTLY_GO is None:
+        return None
+    go = _PLOTLY_GO
+
+    items = list(entries.values() if isinstance(entries, Mapping) else entries)
+    if not items:
+        fig = go.Figure()
+        fig.update_layout(title="空 pool")
+        return fig
+
+    stats: dict[str, dict[str, int]] = defaultdict(lambda: {"pass": 0, "fail": 0})
+    for e in items:
+        decision = bool(e.feedback.decision) if e.feedback else False
+        key = "pass" if decision else "fail"
+        stats[e.operation][key] += 1
+
+    ops = sorted(stats.keys())
+    pass_counts = [stats[o]["pass"] for o in ops]
+    fail_counts = [stats[o]["fail"] for o in ops]
+
+    fig = go.Figure()
+    fig.add_trace(go.Bar(
+        x=ops, y=pass_counts,
+        name="pass", marker_color="#54A24B",
+        text=[str(c) for c in pass_counts], textposition="inside",
+    ))
+    fig.add_trace(go.Bar(
+        x=ops, y=fail_counts,
+        name="fail", marker_color="#E45756",
+        text=[str(c) for c in fail_counts], textposition="inside",
+    ))
+
+    fig.update_layout(
+        title=title or "Operation 通过率",
+        barmode="stack",
+        xaxis_title="operation",
+        yaxis_title="count",
+        height=400,
+        plot_bgcolor="white",
+    )
+    return fig

QuantNodes/core/visualization/lineage_dag.py

@@ -0,0 +1,203 @@
+"""谱系 DAG 布局 — BFS 分层 + 节点定位。
+
+返回:
+    - nodes: list of (entry_id, x, y, label, color, metadata)
+    - edges: list of (parent_id, child_id)
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Mapping
+
+from ..trajectory import TrajectoryEntry, Operation
+
+
+# 节点颜色 (按 operation) — M1: 改用 Operation enum 自动同步
+_OPERATION_COLORS = {
+    Operation.ORIGINAL.value: "#4C78A8",
+    Operation.MUTATION.value: "#F58518",
+    Operation.CROSSOVER.value: "#E45756",
+}
+
+
+def build_lineage_layout(
+    entries: Mapping[str, TrajectoryEntry] | list[TrajectoryEntry],
+    metric: str = "sharpe",
+) -> dict[str, Any]:
+    """构造谱系 DAG 布局。
+
+    Args:
+        entries: TrajectoryEntry 列表或 dict
+        metric: 用于节点大小/颜色的指标 (默认 sharpe)
+
+    Returns:
+        dict: {
+            'nodes': [{
+                'id', 'x', 'y', 'label', 'color', 'size',
+                'metric', 'operation', 'round_idx',
+            }, ...],
+            'edges': [{'source', 'target', 'color'}, ...],
+        }
+    """
+    items = list(entries.values() if isinstance(entries, Mapping) else entries)
+    if not items:
+        return {"nodes": [], "edges": []}
+
+    # 1. 分层: BFS 找每个节点的 round_idx (depth)
+    depths: dict[str, int] = {}
+    for e in items:
+        if not e.parent_ids:
+            depths[e.entry_id] = 0
+        else:
+            # 找最深 parent + 1
+            max_parent_depth = -1
+            for pid in e.parent_ids:
+                if pid in depths:
+                    max_parent_depth = max(max_parent_depth, depths[pid])
+            depths[e.entry_id] = max_parent_depth + 1
+
+    # 2. 按 depth 分组
+    by_depth: dict[int, list[TrajectoryEntry]] = defaultdict(list)
+    for e in items:
+        by_depth[depths[e.entry_id]].append(e)
+
+    # 3. 节点布局: x = index in layer, y = depth
+    nodes = []
+    for depth in sorted(by_depth.keys()):
+        layer = by_depth[depth]
+        for x_idx, e in enumerate(layer):
+            metric_val = float((e.metrics or {}).get(metric, 0) or 0)
+            op = e.operation
+            color = _OPERATION_COLORS.get(op, "#999999")
+            # 节点大小: 按 metric (min 10, max 30)
+            size = 10 + min(20, max(0, metric_val) * 4)
+            name = e.feedback.factor_name if e.feedback else e.entry_id[:8]
+            decision = e.feedback.decision if e.feedback else False
+            nodes.append({
+                "id": e.entry_id,
+                "x": x_idx,
+                "y": depth,
+                "label": f"{name}<br>r{depth} {op}<br>{metric}={metric_val:.2f}",
+                "color": color,
+                "size": size,
+                "metric": metric_val,
+                "operation": op,
+                "round_idx": depth,
+                "decision": decision,
+            })
+
+    # 4. 边: parent_id → child_id
+    edges = []
+    by_id = {e.entry_id: e for e in items}
+    for e in items:
+        for pid in e.parent_ids:
+            if pid in by_id:
+                parent_op = by_id[pid].operation
+                edges.append({
+                    "source": pid,
+                    "target": e.entry_id,
+                    "color": _OPERATION_COLORS.get(parent_op, "#999999"),
+                })
+
+    return {"nodes": nodes, "edges": edges}
+
+
+def lineage_dag_figure(entries, metric: str = "sharpe", title: str | None = None) -> Any:
+    """生成 Plotly Figure (交互式谱系 DAG)。
+
+    Args:
+        entries: TrajectoryEntry 列表
+        metric: 用于节点大小/颜色的指标
+        title: 图标题
+
+    Returns:
+        plotly.graph_objects.Figure, or None if plotly is not installed.
+    """
+    # v3.0.0 graceful degradation: return None when plotly is unavailable.
+    try:
+        import plotly.graph_objects as go
+    except ImportError:
+        import warnings
+        warnings.warn(
+            "plotly not installed; lineage_dag_figure will return None. "
+            "Install plotly: pip install plotly",
+            ImportWarning,
+            stacklevel=2,
+        )
+        return None
+
+    layout = build_lineage_layout(entries, metric=metric)
+    if not layout["nodes"]:
+        fig = go.Figure()
+        fig.update_layout(title="空 pool: 无 entry 可视化")
+        return fig
+
+    # 节点: scatter (x, y)
+    node_x = [n["x"] for n in layout["nodes"]]
+    node_y = [n["y"] for n in layout["nodes"]]
+    node_color = [n["color"] for n in layout["nodes"]]
+    node_size = [n["size"] for n in layout["nodes"]]
+    node_custom = [n for n in layout["nodes"]]
+
+    # 边: 通过 (source_x, source_y) → (target_x, target_y) 划线
+    by_id = {n["id"]: n for n in layout["nodes"]}
+    edge_x: list[float | None] = []
+    edge_y: list[float | None] = []
+    for e in layout["edges"]:
+        src = by_id.get(e["source"])
+        tgt = by_id.get(e["target"])
+        if src is None or tgt is None:
+            continue
+        edge_x.extend([src["x"], tgt["x"], None])
+        edge_y.extend([src["y"], tgt["y"], None])
+
+    fig = go.Figure()
+
+    # 边先画 (在底层)
+    if edge_x:
+        fig.add_trace(go.Scatter(
+            x=edge_x,
+            y=edge_y,
+            mode="lines",
+            line=dict(width=1.5, color="#888"),
+            hoverinfo="skip",
+            showlegend=False,
+        ))
+
+    # 节点
+    fig.add_trace(go.Scatter(
+        x=node_x,
+        y=node_y,
+        mode="markers+text",
+        marker=dict(
+            size=node_size,
+            color=node_color,
+            line=dict(width=2, color="#222"),
+            opacity=0.85,
+        ),
+        text=[n["label"] for n in layout["nodes"]],
+        textposition="top center",
+        hovertemplate="%{text}<extra></extra>",
+        customdata=node_custom,
+        showlegend=False,
+    ))
+
+    # 图例 (operation 颜色)
+    for op, color in _OPERATION_COLORS.items():
+        fig.add_trace(go.Scatter(
+            x=[None], y=[None],
+            mode="markers",
+            marker=dict(size=12, color=color),
+            name=op,
+            showlegend=True,
+        ))
+
+    fig.update_layout(
+        title=title or f"演化谱系 DAG (按 {metric})",
+        xaxis=dict(title="layer index", showgrid=False, zeroline=False),
+        yaxis=dict(title="round (depth)", autorange="reversed", showgrid=False, zeroline=False),
+        hovermode="closest",
+        height=600,
+        plot_bgcolor="white",
+    )
+    return fig

QuantNodes/core/visualization/metric_distribution.py

@@ -0,0 +1,125 @@
+"""指标分布直方图 — Plotly histogram。"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+# v3.0.0 graceful degradation: if plotly is not installed, the figure
+# functions return None.
+try:
+    import plotly.graph_objects as _PLOTLY_GO
+except ImportError:
+    _PLOTLY_GO = None
+
+    import warnings
+    warnings.warn(
+        "plotly not installed; metric_distribution_figure will return None. "
+        "Install plotly: pip install plotly",
+        ImportWarning,
+        stacklevel=1,
+    )
+
+
+
+def metric_distribution_figure(
+    entries,
+    metric: str = "sharpe",
+    title: str | None = None,
+    n_bins: int = 20,
+) -> Any:
+    """生成 Plotly histogram (按 metric 分桶, 颜色按 operation)。
+
+    Args:
+        entries: TrajectoryEntry 列表
+        metric: 指标名
+        title: 标题
+        n_bins: 直方图桶数
+
+    Returns:
+        plotly.graph_objects.Figure, or None if plotly is not installed.
+    """
+    if _PLOTLY_GO is None:
+        return None
+    go = _PLOTLY_GO
+
+    items = list(entries.values() if isinstance(entries, Mapping) else entries)
+    # 按 operation 分组
+    by_op: dict[str, list[float]] = {}
+    for e in items:
+        val = (e.metrics or {}).get(metric)
+        if val is None:
+            continue
+        op = e.operation
+        by_op.setdefault(op, []).append(float(val))
+
+    if not by_op:
+        fig = go.Figure()
+        fig.update_layout(title=f"无 {metric} 指标数据")
+        return fig
+
+    fig = go.Figure()
+    for op, vals in sorted(by_op.items()):
+        fig.add_trace(go.Histogram(
+            x=vals,
+            name=op,
+            opacity=0.7,
+            xbins=dict(size=(max(vals) - min(vals)) / n_bins if max(vals) > min(vals) else 1),
+            hovertemplate=f"{op}<br>{metric}=%{{x:.4f}}<br>count=%{{y}}<extra></extra>",
+        ))
+
+    fig.update_layout(
+        title=title or f"{metric} 分布 (按 operation 着色)",
+        barmode="overlay",
+        xaxis_title=metric,
+        yaxis_title="count",
+        height=450,
+        plot_bgcolor="white",
+    )
+    return fig
+
+
+def metric_per_round_figure(
+    entries,
+    metric: str = "sharpe",
+    title: str | None = None,
+) -> Any:
+    """每轮 best metric 趋势线 (line chart)。"""
+    if _PLOTLY_GO is None:
+        return None
+    go = _PLOTLY_GO
+
+    items = list(entries.values() if isinstance(entries, Mapping) else entries)
+    if not items:
+        fig = go.Figure()
+        fig.update_layout(title="空 pool")
+        return fig
+
+    # 按 round 分组, 取每轮 max
+    by_round: dict[int, list[float]] = {}
+    for e in items:
+        val = (e.metrics or {}).get(metric)
+        if val is None:
+            continue
+        by_round.setdefault(e.round_idx, []).append(float(val))
+
+    rounds = sorted(by_round.keys())
+    bests = [max(by_round[r]) for r in rounds]
+    means = [sum(by_round[r]) / len(by_round[r]) for r in rounds]
+
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(
+        x=rounds, y=bests, mode="lines+markers",
+        name=f"best {metric}", line=dict(color="green", width=3),
+    ))
+    fig.add_trace(go.Scatter(
+        x=rounds, y=means, mode="lines+markers",
+        name=f"mean {metric}", line=dict(color="blue", width=2, dash="dash"),
+    ))
+
+    fig.update_layout(
+        title=title or f"{metric} per round 趋势",
+        xaxis_title="round",
+        yaxis_title=metric,
+        height=400,
+        plot_bgcolor="white",
+    )
+    return fig

QuantNodes/core/visualization/report.py

@@ -0,0 +1,68 @@
+"""Visualization report — generate_html() 主入口, 拼接 3 图 + 概览表。
+
+Phase 1.3: 内部委托给 ReportBuilder, 保留向后兼容 API。
+新代码推荐使用 ReportBuilder 流式 API。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from QuantNodes.core.trajectory.entry import TrajectoryEntry
+
+from .builder import ReportBuilder
+
+
+def generate_report(
+    entries: list[TrajectoryEntry] | Mapping[str, TrajectoryEntry],
+    metric: str = "sharpe",
+    title: str = "QuantNodes 演化实验报告",
+) -> dict[str, Any]:
+    """生成 4 个 Plotly Figure (不输出 HTML)。
+
+    Phase 1.3: 内部委托 ReportBuilder.with_evolve_preset()。
+    返回格式保持向后兼容 (dict with overview + figure keys)。
+
+    Returns:
+        dict: {
+            'overview': {...},
+            'lineage_dag': go.Figure,
+            'metric_distribution': go.Figure,
+            'metric_per_round': go.Figure,
+            'gate_breakdown': go.Figure,
+            'operation_breakdown': go.Figure,
+        }
+    """
+    builder = (
+        ReportBuilder()
+        .with_title(title)
+        .with_evolve_preset(entries, metric=metric)
+    )
+    return builder.build().to_dict()
+
+
+def generate_html(
+    entries,
+    metric: str = "sharpe",
+    title: str = "QuantNodes 演化实验报告",
+    output_path: str | Path | None = None,
+) -> str:
+    """生成完整 HTML 报告, 含 4 个交互图 + 概览表。
+
+    Phase 1.3: 内部委托 ReportBuilder.build_to_html()。
+
+    Args:
+        entries: TrajectoryEntry 列表
+        metric: 用于可视化的指标
+        title: 报告标题
+        output_path: 若指定, 写入文件; 否则返回字符串
+
+    Returns:
+        str: HTML 内容 (若 output_path=None)
+    """
+    return (
+        ReportBuilder()
+        .with_title(title)
+        .with_evolve_preset(entries, metric=metric)
+        .build_to_html(output_path=output_path)
+    )

QuantNodes/database_node/__init__.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""database_node - 数据库节点统一入口
+
+支持 SQLite, DuckDB, MySQL, ClickHouse, CSV, Parquet 等数据源
+
+Usage:
+    from QuantNodes.database_node import (
+        SQLiteNode,
+        DuckDBNode,
+        MySQLNode,
+        ClickHouseNode,
+        CSVNode,
+        ParquetNode,
+    )
+
+    # SQLite 内存模式
+    sqlite = SQLiteNode(":memory:")
+    sqlite.connect()
+
+    # DuckDB 文件模式
+    duckdb = DuckDBNode("/data/analysis.duckdb")
+
+    # MySQL 带连接池
+    mysql = MySQLNode(
+        host="localhost",
+        user="root",
+        passwd="password",
+        db="mydb",
+        pool_size=20
+    )
+
+    # ClickHouse HTTP 接口
+    ch = ClickHouseNode(
+        host="localhost",
+        user="default",
+        passwd="",
+        database="default"
+    )
+
+    # CSV 读取
+    csv = CSVNode("/data/users.csv")
+    df = csv.query("SELECT * WHERE age > 18")
+"""
+
+from QuantNodes.database_node.base import BaseDBNode
+from QuantNodes.database_node.sqlite_node import SQLiteNode
+from QuantNodes.database_node.duckdb_node import DuckDBNode
+from QuantNodes.database_node.mysql_node import MySQLNode
+from QuantNodes.database_node.clickhouse_node import ClickHouseNode
+from QuantNodes.database_node.csv_node import CSVNode
+from QuantNodes.database_node.parquet_node import ParquetNode
+from QuantNodes.database_node.factory import (
+    create_db_node,
+    register_db_node,
+    available_sources,
+)
+
+__all__ = [
+    'BaseDBNode',
+    'SQLiteNode',
+    'DuckDBNode',
+    'MySQLNode',
+    'ClickHouseNode',
+    'CSVNode',
+    'ParquetNode',
+    'create_db_node',
+    'register_db_node',
+    'available_sources',
+]