quantnodes 3.0.0__py3-none-any.whl

QuantNodes/agent/config_mapper.py

@@ -0,0 +1,293 @@
+# coding=utf-8
+"""Translate ``.env`` QUANTNODES__* vars into HKUDS nanobot config.json.
+
+Nanobot 0.2.1 reads a JSON config (``.agent/nanobot_config.json`` by
+convention) with shape (verified against ``nanobot.config.schema.Config``)::
+
+    {
+      "agents": {"defaults": {"workspace": "<path>", "model": "...", "provider": "openai"}},
+      "providers": {
+        "<slot_name>": {
+          "api_key": "sk-...",
+          "api_base": "https://api.openai.com/v1",
+          "api_type": "chat_completions" | "responses" | "auto"
+        },
+        ...
+      },
+      "channels": {
+        "websocket": {"enabled": true, "host": "127.0.0.1", "port": 8765, ...},
+        "feishu":    {"enabled": false, "app_id": "...", "app_secret": "...", ...}
+      }
+    }
+
+Provider slots (defined in ProvidersConfig schema):
+- ``openai``            — OpenAI direct
+- ``anthropic``         — Anthropic direct
+- ``azure_openai``      — Azure OpenAI
+- ``bedrock``           — AWS Bedrock
+- ``custom``            — Generic OpenAI-compatible endpoint
+- ``ollama``            — Ollama local (api_base=http://localhost:11434/v1)
+- ``lm_studio``         — LM Studio local
+- ``vllm``              — vLLM local
+- ``openrouter``        — OpenRouter aggregator
+- ``deepseek``          — DeepSeek direct
+- ``groq``              — Groq
+- ``gemini``            — Google Gemini
+- ``minimax``           — MiniMax (provider model aliases)
+- ... (30+ total)
+
+Channels (defined as ``ChannelsConfig`` extras in upstream schema):
+
+- ``websocket`` — nanobot WebSocket channel + WebUI SPA host. Default port 18080.
+- ``feishu``    — Feishu/Lark bot (WebSocket long connection, no public IP needed).
+                  Requires ``FEISHU_APP_ID`` + ``FEISHU_APP_SECRET`` env vars.
+
+Slot resolution (URL-based heuristics):
+- base URL contains ``anthropic`` -> ``anthropic`` (or ``minimax_anthropic`` if MiniMax endpoint)
+- base URL contains ``azure``    -> ``azure_openai``
+- base URL contains ``ollama``   -> ``ollama``
+- otherwise (incl. local OpenAI-compatible) -> ``custom``
+
+``agents.defaults.provider`` is set to the resolved slot name so that the
+upstream ``_match_provider`` helper finds the right provider config.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from QuantNodes.constants import DEFAULT_HOST, DEFAULT_WEBSOCKET_PORT, DEFAULT_LLM_MODEL
+
+logger = logging.getLogger(__name__)
+
+
+CONFIG_FILENAME = "nanobot_config.json"
+
+
+def _resolve_slot(base_url: str, api_key: str) -> tuple[str, str]:
+    """Return (slot_name, api_type) inferred from URL/key hints.
+
+    ``slot_name`` matches one of the predefined slots in ProvidersConfig
+    schema (e.g. ``openai``, ``anthropic``, ``azure_openai``, ``custom``).
+    ``api_type`` is the request API surface (``chat_completions``,
+    ``responses``, or ``auto``).
+    """
+    u = (base_url or "").lower()
+    if "anthropic" in u and "minimax" not in u and "minimaxi" not in u:
+        # Anthropic native endpoint (api.anthropic.com or proxied clones).
+        return "anthropic", "auto"
+    if "azure" in u:
+        return "azure_openai", "responses"
+    if "ollama" in u or ":11434" in u:
+        return "ollama", "auto"
+    # v3.0.0: MiniMax provider (``api.minimaxi.com`` /
+    # ``api.minimax.com``) exposes an OpenAI-compatible ``/v1/chat/completions``
+    # endpoint, NOT the Anthropic ``/v1/messages`` surface — so the
+    # ``minimax_anthropic`` slot (which forces Anthropic schema) would 404.
+    # Use the ``custom`` slot with ``chat_completions`` API type instead.
+    if "minimaxi" in u or "minimax" in u:
+        return "custom", "chat_completions"
+    if api_key and api_key.startswith("sk-ant-"):
+        return "anthropic", "auto"
+    # Default: OpenAI-compatible endpoint goes to ``custom`` slot
+    # (which is the documented fallback for OpenAI-compatible URLs).
+    return "custom", "chat_completions"
+
+
+def _build_websocket_config(
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_WEBSOCKET_PORT,
+    ws_token: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Build the WebSocket channel config block.
+
+    The WebSocket channel is the upstream nanobot gateway. It serves:
+
+    - The WebUI SPA on port 18080 (mounted via ``ChannelManager(webui_static_dist=True)``)
+    - The WebSocket endpoint at ``ws://{host}:{port}/{path}?token=...``
+    - REST surface for sessions / messages / commands / sidebar state
+
+    Configuration knobs (all map to ``nanobot.channels.websocket.WebSocketConfig``):
+
+    - ``host``               — bind address (default 127.0.0.1, loopback only)
+    - ``port``               — WS port (default 8765; the SPA lives on gateway.port)
+    - ``path``               — WS upgrade path (default ``/``)
+    - ``websocketRequiresToken`` — require token for handshake (default True)
+    - ``streaming``          — enable streaming responses (default True)
+    - ``allowFrom``          — list of allowed ``client_id`` values (default ``["*"]``)
+    """
+    return {
+        "enabled": True,
+        "host": host,
+        "port": port,
+        "path": "/",
+        "tokenIssuePath": "/webui/token",
+        "websocketRequiresToken": True,
+        "allowFrom": ["*"],
+        "streaming": True,
+        # v3.0.0: when binding to 0.0.0.0 (all interfaces), nanobot's
+        # WebSocketConfig validates that a token is set — this prevents
+        # unauthenticated access from the LAN. Use NANOBOT_WS_TOKEN env
+        # var if provided; otherwise auto-generate one on startup.
+        **({"token": ws_token} if ws_token else {}),
+    }
+
+
+def _build_feishu_config(env: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """Build the Feishu channel config block from env vars.
+
+    Required env vars (Stage 5.4):
+
+    - ``FEISHU_APP_ID``     — application ID from Feishu Open Platform
+    - ``FEISHU_APP_SECRET`` — application secret
+
+    Optional:
+
+    - ``FEISHU_ENCRYPT_KEY``         — event encryption key
+    - ``FEISHU_VERIFICATION_TOKEN``  — event verification token
+    - ``FEISHU_DOMAIN`` (``feishu`` / ``lark``) — domain selector
+    - ``FEISHU_GROUP_POLICY`` (``mention`` / ``open``) — group chat policy
+    - ``FEISHU_REPLY_TO_MESSAGE``     — whether to quote the user's message
+
+    If required env vars are missing the channel is disabled (returns
+    ``{"enabled": False}``). The Feishu SDK (``lark_oapi``) is an *optional*
+    runtime dep — even when this config block is enabled, the channel will
+    refuse to start if the SDK isn't installed.
+
+    Reference: ``nanobot.channels.feishu.FeishuConfig``
+    """
+    env = env or os.environ
+    app_id = env.get("FEISHU_APP_ID", "").strip()
+    app_secret = env.get("FEISHU_APP_SECRET", "").strip()
+    if not (app_id and app_secret):
+        return {"enabled": False}
+
+    allow_from_raw = env.get("FEISHU_ALLOW_FROM", "").strip()
+    allow_from: List[str] = (
+        [s.strip() for s in allow_from_raw.split(",") if s.strip()]
+        if allow_from_raw else []
+    )
+
+    return {
+        "enabled": True,
+        "appId": app_id,
+        "appSecret": app_secret,
+        "encryptKey": env.get("FEISHU_ENCRYPT_KEY", "").strip(),
+        "verificationToken": env.get("FEISHU_VERIFICATION_TOKEN", "").strip(),
+        "allowFrom": allow_from,
+        "domain": env.get("FEISHU_DOMAIN", "feishu").strip() or "feishu",
+        "groupPolicy": env.get("FEISHU_GROUP_POLICY", "mention").strip() or "mention",
+        "replyToMessage": env.get("FEISHU_REPLY_TO_MESSAGE", "false").lower() in ("1", "true", "yes"),
+        "streaming": True,
+    }
+
+
+def build_nanobot_config(
+    workspace: Path,
+    user_config: Optional[Dict[str, Any]] = None,
+    channel_overrides: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Build a nanobot-compatible config dict from env + user_config.
+
+    ``channel_overrides`` lets the caller (typically the FastAPI runtime)
+    force specific channel settings — e.g. websocket host/port derived
+    from ``NANOBOT_GATEWAY_HOST``/``NANOBOT_GATEWAY_PORT``.
+    """
+    user_config = user_config or {}
+    channel_overrides = channel_overrides or {}
+
+    api_key = user_config.get("api_key") or os.environ.get("QUANTNODES__LLM__API_KEY", "")
+    base_url = user_config.get("api_base") or os.environ.get("QUANTNODES__LLM__BASE_URL", "")
+    model = user_config.get("model") or os.environ.get("QUANTNODES__LLM__MODEL", DEFAULT_LLM_MODEL)
+
+    slot, api_type = _resolve_slot(base_url, api_key)
+
+    provider_block: Dict[str, Any] = {}
+    # ``api_type`` is only allowed on the ``openai`` slot (upstream schema
+    # validation); other slots always use the provider-default API surface.
+    if slot == "openai":
+        provider_block["apiType"] = api_type
+    if api_key:
+        provider_block["apiKey"] = api_key
+    if base_url:
+        provider_block["apiBase"] = base_url
+
+    # ── Channels ────────────────────────────────────────────────────────
+    channels: Dict[str, Any] = {}
+
+    ws_override = channel_overrides.get("websocket") or {}
+    ws_enabled = ws_override.get("enabled", True)
+    if ws_enabled:
+        ws_host = ws_override.get("host", DEFAULT_HOST)
+        # v3.0.0: when binding to 0.0.0.0, nanobot requires a token for security.
+        # Use NANOBOT_WS_TOKEN env var if set; otherwise auto-generate one.
+        ws_token = os.environ.get("NANOBOT_WS_TOKEN", "")
+        if not ws_token and ws_host in ("0.0.0.0", "::"):
+            import secrets
+            ws_token = secrets.token_urlsafe(32)
+            logger.info("Auto-generated WebSocket token for LAN access: %s...", ws_token[:12])
+        channels["websocket"] = _build_websocket_config(
+            host=ws_host,
+            port=int(ws_override.get("port", DEFAULT_WEBSOCKET_PORT)),
+            ws_token=ws_token or None,
+        )
+    else:
+        # Caller explicitly disabled websocket — emit the block anyway so
+        # nanobot sees ``enabled: false`` and skips it deterministically.
+        channels["websocket"] = {"enabled": False}
+
+    fs_override = channel_overrides.get("feishu") or {}
+    feishu_config = _build_feishu_config()
+    if fs_override:
+        # Allow caller to force enabled/disabled even when env vars are
+        # missing (useful for tests).
+        feishu_config.update(fs_override)
+    channels["feishu"] = feishu_config
+
+    # ── Top-level ───────────────────────────────────────────────────────
+    # v3.1.0: MCP servers removed from auto-generated config.
+    # QuantTools are registered directly on the agent's ToolRegistry
+    # via ``register_all_quant_tools()`` in nanobot_runtime.py.
+    # The MCP server can be started independently for external clients:
+    #   python -m QuantNodes.mcp_server --transport http --port 8765
+    # Or via ``quantnodes serve --mcp`` (optional subprocess).
+    config: Dict[str, Any] = {
+        "agents": {
+            "defaults": {
+                "workspace": str(workspace),
+                "model": model,
+                "provider": slot,
+            },
+        },
+        "providers": {
+            slot: provider_block,
+        },
+        "channels": channels,
+    }
+
+    if "max_tokens" in user_config:
+        config["agents"]["defaults"]["maxTokens"] = int(user_config["max_tokens"])
+
+    return config
+
+
+def write_nanobot_config(workspace: Path, config: Dict[str, Any]) -> Path:
+    """Persist ``config`` as JSON inside ``workspace`` and return the path."""
+    workspace.mkdir(parents=True, exist_ok=True)
+    target = workspace / CONFIG_FILENAME
+    target.write_text(json.dumps(config, indent=2, ensure_ascii=False), encoding="utf-8")
+    logger.info("Wrote nanobot config: %s", target)
+    return target
+
+
+__all__ = [
+    "build_nanobot_config",
+    "write_nanobot_config",
+    "CONFIG_FILENAME",
+    "_build_websocket_config",
+    "_build_feishu_config",
+]

QuantNodes/agent/core/__init__.py

@@ -0,0 +1,19 @@
+# coding=utf-8
+"""
+核心引擎模块 (v3.0.0 精简版)
+
+v3.0.0 之前本目录包含自写的 loop/runner/memory/dream/...，已全部由
+HKUDS/nanobot 0.2.1 上游替代。
+
+当前保留：
+- quant_dream.py - 量化专属 Dream 钩子（QuantDreamHook）
+- dream.py - 向后兼容 shim
+"""
+
+from .quant_dream import DreamEngine, QuantDreamHook, QuantDreamInsight
+
+__all__ = [
+    "DreamEngine",
+    "QuantDreamHook",
+    "QuantDreamInsight",
+]

QuantNodes/agent/core/dream.py

@@ -0,0 +1,47 @@
+# coding=utf-8
+"""
+向后兼容 shim — 量化专属 Dream 引擎。
+
+v3.0.0 起，Dream 相关实现已迁移到 ``QuantNodes.agent.core.quant_dream``。
+本模块保留旧导入路径 ``from QuantNodes.agent.core.dream import ...`` 的可用性。
+
+替代映射：
+- ``DreamEngine``        -> ``QuantNodes.agent.core.quant_dream.DreamEngine``
+- ``DreamStore``         -> 已删除（由 nanobot 上游 ``MemoryStore`` 替代，见 .agent/memory/）
+- ``MemoryStore``        -> 已删除（由 nanobot 上游 ``nanobot.agent.memory.MemoryStore`` 替代）
+- ``MemoryManager``      -> 已删除（迁移到 nanobot 的 MEMORY.md/SOUL.md 文件系统约定）
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from .quant_dream import DreamEngine, QuantDreamHook, QuantDreamInsight
+
+warnings.warn(
+    "QuantNodes.agent.core.dream is a backward-compatibility shim. "
+    "Import from QuantNodes.agent.core.quant_dream instead. "
+    "DreamStore/MemoryStore/MemoryManager have been replaced by the "
+    "upstream nanobot memory subsystem.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+
+class _RemovedSymbol:
+    """Sentinel for symbols removed in v3.0.0 (nanobot upstream replacement)."""
+
+
+DreamStore = _RemovedSymbol
+MemoryStore = _RemovedSymbol
+MemoryManager = _RemovedSymbol
+
+
+__all__ = [
+    "DreamEngine",
+    "DreamStore",
+    "MemoryStore",
+    "MemoryManager",
+    "QuantDreamHook",
+    "QuantDreamInsight",
+]

QuantNodes/agent/core/quant_dream.py

@@ -0,0 +1,274 @@
+# coding=utf-8
+"""QuantDreamHook - 量化专属 Dream 钩子（v3.0.0 新增）。
+
+挂在 HKUDS nanobot 的 AgentHook 系统上，扩展通用 Dream 整合（上游
+nanobot/agent/memory.py::Dream + Consolidator）以覆盖量化场景：
+
+1. **因子洞察** - 提取 IC 表现好的因子，反思构造逻辑
+2. **回测模式** - 记录过拟合/未来函数/手续费过高等问题模式
+3. **策略启发** - 跨策略对比，识别共同成功因素
+4. **风险事件** - 大回撤/极端行情下的策略表现
+5. **代码模式** - LLM 生成的常见代码 bug
+
+输出：``.agent/memory/topic-quant-dream.md``
+
+向后兼容：
+- ``QuantNodes.agent.core.dream.DreamEngine`` 仍可用（re-export 自本模块）
+- 旧 ``QuantNodes.agent.core.dream.DreamStore`` 由 nanobot upstream 替代
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+FACTOR_KEYWORDS = (
+    "alpha", "factor", "ic", "rank", "momentum", "reversal",
+    "value", "quality", "volatility",
+)
+BACKTEST_KEYWORDS = (
+    "backtest", "sharpe", "drawdown", "annualized", "win_rate",
+    "profit_loss_ratio", "icir",
+)
+STRATEGY_KEYWORDS = (
+    "strategy", "pipeline", "weight", "rebalance", "portfolio",
+)
+
+
+@dataclass
+class QuantDreamInsight:
+    """Single quant dream entry."""
+
+    id: str = ""
+    type: str = ""
+    content: str = ""
+    insights: List[str] = field(default_factory=list)
+    confidence: float = 0.7
+    tags: List[str] = field(default_factory=list)
+    timestamp: str = ""
+    source: str = "quant_dream"
+
+    def __post_init__(self):
+        if not self.id:
+            import uuid
+            self.id = f"dream-{uuid.uuid4().hex[:12]}"
+
+    def to_markdown(self) -> str:
+        lines = [f"### {self.timestamp[:10] or 'unknown'} - {self.type}", f"- {self.content}"]
+        for insight in self.insights:
+            lines.append(f"  - {insight}")
+        if self.tags:
+            lines.append(f"  - tags: {', '.join(self.tags)}")
+        return "\n".join(lines) + "\n"
+
+
+class QuantDreamHook:
+    """QuantNodes 专属 Dream 钩子，注入到 nanobot 的 _extra_hooks 列表。
+
+    Usage::
+
+        from QuantNodes.agent.core.quant_dream import QuantDreamHook
+        from QuantNodes.agent import Agent
+        agent = Agent(workspace=".agent")
+        agent.loop._extra_hooks.append(QuantDreamHook(agent.workspace))
+    """
+
+    DEFAULT_INTERVAL = 10
+    DEFAULT_MIN_CONFIDENCE = 0.5
+
+    def __init__(
+        self,
+        workspace: Path,
+        interval: int = DEFAULT_INTERVAL,
+        min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+    ):
+        self.workspace = Path(workspace).expanduser().resolve()
+        self.memory_dir = self.workspace / "memory"
+        self.memory_dir.mkdir(parents=True, exist_ok=True)
+        self.topic_file = self.memory_dir / "topic-quant-dream.md"
+        self.interval = interval
+        self.min_confidence = min_confidence
+        self._counter: Dict[str, int] = {}
+
+    def should_analyze(self, user_content: str, assistant_content: str) -> bool:
+        """Return True iff the conversation touches any quant topic.
+
+        Uses word-boundary regex matching to avoid false positives like
+        ``"ic" in "nice"`` or ``"day" in "today"``.
+        """
+        import re
+
+        combined = (user_content + " " + assistant_content).lower()
+        for kw in FACTOR_KEYWORDS + BACKTEST_KEYWORDS + STRATEGY_KEYWORDS:
+            if re.search(rf"\b{re.escape(kw)}\b", combined):
+                return True
+        return False
+
+    def analyze_session(
+        self,
+        session_key: str,
+        user_content: str,
+        assistant_content: str,
+    ) -> Optional[QuantDreamInsight]:
+        """Run quant-specific analysis on a completed session turn.
+
+        Lightweight heuristic — no LLM call. Returns ``None`` if no insight.
+        """
+        if not self.should_analyze(user_content, assistant_content):
+            return None
+
+        kind = self._classify(user_content + " " + assistant_content)
+        content, insights = self._extract_insights(user_content, assistant_content, kind)
+
+        if not insights:
+            return None
+
+        from datetime import datetime, timezone
+        return QuantDreamInsight(
+            type=kind,
+            content=content,
+            insights=insights,
+            confidence=0.7,
+            tags=[kind, "auto"],
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            source="quant_dream",
+        )
+
+    def append(self, dream: QuantDreamInsight) -> None:
+        """Append an insight to the topic file (idempotent append)."""
+        if dream.confidence < self.min_confidence:
+            return
+        existing = self.topic_file.read_text(encoding="utf-8") if self.topic_file.exists() else "# Quant Dream Insights\n\n"
+        self.topic_file.write_text(existing + dream.to_markdown(), encoding="utf-8")
+        logger.info("Quant dream appended: type=%s", dream.type)
+
+    def get_recent_dreams(self, limit: int = 20) -> List[QuantDreamInsight]:
+        """Parse the topic file and return the most recent ``limit`` insights.
+
+        Lightweight parser — sufficient for the API listing endpoint.
+        """
+        if not self.topic_file.exists():
+            return []
+
+        text = self.topic_file.read_text(encoding="utf-8")
+        dreams: List[QuantDreamInsight] = []
+        current_type = ""
+        current_content = ""
+        current_insights: List[str] = []
+        current_tags: List[str] = []
+        current_date = ""
+
+        for raw_line in text.splitlines():
+            line = raw_line.rstrip()
+            if line.startswith("### "):
+                if current_content or current_insights:
+                    dreams.append(self._build(
+                        current_date, current_type, current_content,
+                        current_insights, current_tags,
+                    ))
+                current_date = line[4:14] if len(line) >= 14 else ""
+                rest = line[4:].split(" - ", 1)
+                current_type = rest[1] if len(rest) > 1 else rest[0]
+                current_content = ""
+                current_insights = []
+                current_tags = []
+            elif line.startswith("- "):
+                current_content = line[2:]
+            elif line.startswith("  - "):
+                item = line[4:]
+                if item.startswith("tags: "):
+                    current_tags = [t.strip() for t in item[6:].split(",") if t.strip()]
+                else:
+                    current_insights.append(item)
+
+        if current_content or current_insights:
+            dreams.append(self._build(
+                current_date, current_type, current_content,
+                current_insights, current_tags,
+            ))
+
+        return list(reversed(dreams[-limit:]))
+
+    @staticmethod
+    def _build(date: str, type_: str, content: str, insights: List[str], tags: List[str]) -> QuantDreamInsight:
+        return QuantDreamInsight(
+            id=f"dream-{hash((date, type_, content)) & 0xffffffffffff:012x}",
+            type=type_,
+            content=content,
+            insights=insights,
+            tags=tags,
+            confidence=0.7,
+            timestamp=f"{date}T00:00:00Z" if date else "",
+            source="quant_dream",
+        )
+
+    def tick(self, session_key: str) -> None:
+        """Increment session counter; returns whether to fire analysis this round."""
+        n = self._counter.get(session_key, 0) + 1
+        self._counter[session_key] = n
+        return None  # analysis is triggered externally via analyze_session()
+
+    @staticmethod
+    def _classify(text: str) -> str:
+        lc = text.lower()
+        if any(kw in lc for kw in FACTOR_KEYWORDS):
+            return "factor_insight"
+        if any(kw in lc for kw in BACKTEST_KEYWORDS):
+            return "backtest_pattern"
+        if any(kw in lc for kw in STRATEGY_KEYWORDS):
+            return "strategy_heuristic"
+        return "general"
+
+    @staticmethod
+    def _extract_insights(user: str, assistant: str, kind: str) -> tuple:
+        first_sentence = re.split(r"[.!?\n]", assistant.strip(), maxsplit=1)[0][:200]
+        return (first_sentence or f"{kind} analysis", [assistant[:300]])
+
+
+class DreamEngine:
+    """向后兼容 shim — 旧 ``QuantNodes.agent.core.dream.DreamEngine`` API。
+
+    委托到 QuantDreamHook。保留名称以避免破坏 api/services/dream_service.py。
+    """
+
+    def __init__(self, workspace: Path | str = None, *, dream_store=None):
+        # Accept legacy ``dream_store=`` kwarg for backward compatibility.
+        # The actual store (nanobot MemoryStore) replaces this in v3.0.0;
+        # we only need a workspace path for QuantDreamHook.
+        if workspace is None and dream_store is not None:
+            workspace = getattr(dream_store, "workspace", None) or getattr(dream_store, "memory_dir", None)
+        if workspace is None:
+            workspace = Path(".agent")
+        self.workspace = Path(workspace)
+        self.hook = QuantDreamHook(self.workspace)
+
+    def analyze_conversation(self, user_message: str, assistant_response: str) -> Optional[QuantDreamInsight]:
+        return self.hook.analyze_session("default", user_message, assistant_response)
+
+    def generate_dream(self, dream_type: str, content: str, source: str = "",
+                       insights=None, confidence: float = 0.7, tags=None) -> QuantDreamInsight:
+        from datetime import datetime, timezone
+        dream = QuantDreamInsight(
+            type=dream_type, content=content, insights=list(insights or []),
+            confidence=confidence, tags=list(tags or []), source=source,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+        self.hook.append(dream)
+        return dream
+
+
+__all__ = [
+    "QuantDreamHook",
+    "QuantDreamInsight",
+    "DreamEngine",
+    "FACTOR_KEYWORDS",
+    "BACKTEST_KEYWORDS",
+    "STRATEGY_KEYWORDS",
+]