Skip to content

"Vibe-Trading: Your Personal Trading Agent"

25.1 KB
Raw Blame
"""SwarmTool: tool for the main agent to invoke a swarm multi-agent team.

The user provides a natural-language prompt; the tool auto-selects the best preset and extracts variables.
Blocks synchronously until the run completes and returns a JSON summary.
"""

from __future__ import annotations

import json
import logging
import re
import time
from typing import Any

from src.agent.tools import BaseTool
from src.tools.swarm_variables import build_variables as _build_variables
from src.tools.swarm_variables import merge_variables as _merge_variables

logger = logging.getLogger(__name__)

_POLL_INTERVAL_SECONDS = 5

# How long a user-cancelled run gets to reach a terminal state before the tool
# reports "cancelling" instead of a settled result. Workers honour the cancel
# flag between iterations, so this only covers one in-flight LLM call.
_CANCEL_SETTLE_SECONDS = 20


def _max_wait_seconds() -> int:
    import sys as _sys
    _mod = _sys.modules.get(__name__)
    if _mod is not None and "_MAX_WAIT_SECONDS" in _mod.__dict__:
        return _mod.__dict__["_MAX_WAIT_SECONDS"]
    from src.config.accessor import get_env_config
    return get_env_config().swarm.swarm_timeout

# Preset matching: (preset_name, keyword_patterns, weight_boost). Patterns match user intent (EN + ZH).
_PRESET_KEYWORDS: list[tuple[str, list[str], float]] = [
    (
        "global_allocation_committee",
        [
            r"cross[- ]?market",
            r"global\s+alloc",
            "multi[- ]asset",
            "三市场",
            "全球配置",
            "资产配置",
            "港美.*A股",
            "A股.*加密",
            "加密.*A股",
            "多市场",
        ],
        1.0,
    ),
    (
        "risk_committee",
        [
            r"risk\s+audit",
            "drawdown",
            r"tail\s+risk",
            r"stress\s+test",
            r"\bVaR\b",
            "风控",
            "风险审计",
            "回撤",
            "尾部风险",
            "压力测试",
            "风险评估",
        ],
        1.0,
    ),
    (
        "quant_strategy_desk",
        [
            r"\bquant\b",
            "alpha",
            "factor",
            "backtest",
            "多因子",
            "量化策略",
            "因子",
            "选股",
            "策略.*回测",
        ],
        1.0,
    ),
    (
        "equity_research_team",
        [
            "equity research",
            "stock research",
            "研报",
            "研究报告",
            "行业分析",
            "个股分析",
            "投资分析",
            "macro.*sector",
            "投资机会",
        ],
        0.85,
    ),
    (
        "factor_research_committee",
        [
            r"factor\s+research",
            r"\bIC\b",
            "ICIR",
            "因子委员会",
            "因子研究",
        ],
        0.9,
    ),
    (
        "event_driven_task_force",
        [
            r"M&A",
            "merger",
            "insider",
            r"earnings\s+surprise",
            "事件驱动",
            "并购",
            "财报",
        ],
        0.9,
    ),
    (
        "etf_allocation_desk",
        [
            r"\bETF\b",
            r"index\s+fund",
            "指数基金",
            "ETF配置",
        ],
        0.9,
    ),
    (
        "derivatives_strategy_desk",
        [
            r"\boptions?\b",
            r"\bcall\s+options?\b",
            r"\bput\s+options?\b",
            r"\bGreeks?\b",
            r"implied\s+vol",
            r"\bIV\b",
            "期权",
            "衍生品",
        ],
        0.9,
    ),
    (
        "crypto_research_lab",
        [
            r"\bBTC\b",
            r"\bETH\b",
            r"\bSOL\b",
            r"\b(?:XRP|BNB|ADA|DOGE|AVAX|DOT|LINK|TON|LTC|MATIC)\b",
            "crypto",
            "bitcoin",
            "加密",
            "数字货币",
        ],
        0.95,
    ),
    (
        "credit_research_team",
        [
            r"credit\s+bond",
            "LGFV",
            r"\bYTM\b",
            "利差",
            "信用债",
            "城投",
        ],
        0.9,
    ),
    (
        "convertible_bond_team",
        [
            "convertible",
            "可转债",
            r"\bCB\b",
        ],
        0.9,
    ),
    (
        "fundamental_research_team",
        [
            "fundamental",
            r"deep\s+dive",
            "财务",
            "基本面",
        ],
        0.85,
    ),
    (
        "commodity_research_team",
        [
            "commodity",
            "crude",
            "gold",
            "copper",
            r"iron\s+ore",
            "商品",
            "原油",
            "黄金",
            "铜",
            "铁矿石",
            "白银",
            "天然气",
        ],
        0.9,
    ),
    (
        "fund_selection_panel",
        [
            r"\bFOF\b",
            r"mutual\s+fund",
            "基金筛选",
            "选基",
        ],
        0.85,
    ),
    (
        "social_alpha_team",
        [
            r"social\s+media",
            "twitter",
            "reddit",
            "社媒",
            "舆情",
        ],
        0.85,
    ),
    (
        "geopolitical_war_room",
        [
            "geopolitical",
            r"war\s+risk",
            "sanction",
            "地缘",
            "危机场景",
        ],
        0.9,
    ),
    (
        "pairs_research_lab",
        [
            r"pairs\s+trading",
            "cointegration",
            "配对",
            "统计套利",
        ],
        0.9,
    ),
    (
        "value_investing_committee",
        [
            r"value\s+investing",
            "价值投资",
            r"\bbuffett\b",
            "巴菲特",
            r"\bmunger\b",
            "芒格",
            "段永平",
            "李录",
            "四大师",
            r"four\s+master",
        ],
        0.9,
    ),
    (
        "investment_committee",
        [
            r"investment\s+committee",
            "投委会",
            "投资决策",
        ],
        0.85,
    ),
    (
        "macro_strategy_forum",
        [
            r"\bFed\b",
            r"\bCPI\b",
            r"\bPMI\b",
            "macro",
            "货币政策",
            "宏观",
        ],
        0.9,
    ),
    (
        "statistical_arbitrage_desk",
        [
            r"statistical\s+arbitrage",
            r"stat\s+arb",
            "统计套利",
        ],
        0.9,
    ),
    (
        "sentiment_intelligence_team",
        [
            "sentiment",
            r"fear\s+and\s+greed",
            "情绪",
            "恐慌",
        ],
        0.85,
    ),
    (
        "technical_analysis_panel",
        [
            r"technical\s+analysis",
            r"\bRSI\b",
            r"\bMACD\b",
            "技术分析",
            "K线",
        ],
        0.85,
    ),
    (
        "sector_rotation_team",
        [
            r"sector\s+rotation",
            "板块轮动",
            "行业轮动",
        ],
        0.85,
    ),
    (
        "portfolio_review_board",
        [
            r"portfolio\s+review",
            "组合复盘",
            "业绩归因",
        ],
        0.85,
    ),
    (
        "ml_quant_lab",
        [
            r"\bML\b",
            r"machine\s+learning",
            "LSTM",
            "XGBoost",
            "机器学习",
            "深度学习",
        ],
        0.9,
    ),
]

def _match_preset(prompt: str) -> str:
    """Match user prompt to best preset using keyword scoring.

    Args:
        prompt: User's natural language prompt.

    Returns:
        Best matching preset name.
    """
    normalized_prompt = re.sub(r"[\s-]+", "_", prompt.strip().lower())
    for preset_name, _, _ in _PRESET_KEYWORDS:
        if re.search(rf"(?<![a-z0-9]){re.escape(preset_name)}(?![a-z0-9])", normalized_prompt):
            return preset_name

    scores: dict[str, float] = {}
    for preset_name, keywords, boost in _PRESET_KEYWORDS:
        score = 0.0
        for kw in keywords:
            if re.search(kw, prompt, re.IGNORECASE):
                score += boost
        scores[preset_name] = score

    best = max(scores, key=scores.get)  # type: ignore[arg-type]
    if scores[best] > 0:
        return best

    return "equity_research_team"


_PRESET_NAMES = {preset_name for preset_name, _, _ in _PRESET_KEYWORDS}
_CONTINUATION_PATTERNS = (
    r"^\s*continue\b",
    r"^\s*resume\b",
    r"^\s*finish\b",
    r"\bcontinue\s+(?:and\s+)?finish\b",
    r"\bcontinue\s+from\b",
    r"\bfinish\s+(?:the\s+)?report\b",
    r"\bcomplete\s+(?:the\s+)?report\b",
    r"\bpick\s+up\s+from\b",
    r"^\s*继续",
    r"^\s*接着",
)


def _normalize_preset_name(value: str) -> str | None:
    """Normalize an explicit preset name and validate it resolves to a preset.

    Names in the static routing table are accepted as before. Names outside it
    are accepted only when they resolve to an actual preset file — which lets
    explicitly named user presets (``~/.vibe-trading/swarm/presets/``) run
    through this tool. Keyword ROUTING stays limited to the curated table: a
    user preset is reachable only by naming it, never by keyword match.
    """
    normalized = re.sub(r"[\s-]+", "_", value.strip().lower())
    if normalized in _PRESET_NAMES:
        return normalized
    from src.swarm.presets import resolve_preset_path

    try:
        if resolve_preset_path(normalized) is not None:
            return normalized
    except ValueError:
        return None
    return None


def _has_preset_signal(prompt: str) -> bool:
    """Return whether prompt contains an explicit preset name or routing keyword."""
    normalized_prompt = re.sub(r"[\s-]+", "_", prompt.strip().lower())
    for preset_name, _, _ in _PRESET_KEYWORDS:
        if re.search(rf"(?<![a-z0-9]){re.escape(preset_name)}(?![a-z0-9])", normalized_prompt):
            return True
    for _, keywords, _ in _PRESET_KEYWORDS:
        for kw in keywords:
            if re.search(kw, prompt, re.IGNORECASE):
                return True
    return False


def _looks_like_continuation_prompt(prompt: str) -> bool:
    """Detect prompts that refer to prior work instead of a fresh swarm task."""
    return any(re.search(pattern, prompt, re.IGNORECASE) for pattern in _CONTINUATION_PATTERNS)


def _resolve_preset(prompt: str, explicit_preset: str | None = None) -> tuple[str | None, str | None]:
    """Resolve the preset to run, returning an error string when ambiguous."""
    if explicit_preset:
        preset = _normalize_preset_name(explicit_preset)
        if preset is None:
            available = ", ".join(sorted(_PRESET_NAMES))
            return None, (
                f"Unknown preset_name '{explicit_preset}'. Available presets: {available}. "
                "User presets in ~/.vibe-trading/swarm/presets/ are also accepted by name."
            )
        return preset, None

    if _looks_like_continuation_prompt(prompt) and not _has_preset_signal(prompt):
        return (
            None,
            "Ambiguous continuation swarm prompt. Reuse the previous swarm result, "
            "or call run_swarm with preset_name and the original full request. "
            "Refusing to auto-route this continuation to equity_research_team.",
        )

    return _match_preset(prompt), None


class SwarmTool(BaseTool):
    """Launch a swarm multi-agent team to execute complex tasks.

    Accepts a natural-language prompt, auto-selects the best preset,
    and blocks synchronously until the swarm run completes or times out.
    """

    name = "run_swarm"
    description = (
        "Run a multi-agent swarm team for complex analysis tasks. "
        "Provide a natural language prompt and, when known, an explicit preset_name from agent/src/swarm/presets "
        "(e.g. equity_research_team, quant_strategy_desk, global_allocation_committee, risk_committee) "
        "so follow-up/continuation prompts do not lose routing context. "
        "Example: run_swarm(prompt='Analyze A-share new energy opportunities for Q2 2026', preset_name='equity_research_team')"
    )
    parameters = {
        "type": "object",
        "properties": {
            "prompt": {
                "type": "string",
                "description": "Natural language description of the analysis task.",
            },
            "preset_name": {
                "type": "string",
                "description": "Optional explicit swarm preset name when the user named one or this is a continuation.",
            },
            "variables": {
                "type": "object",
                "description": (
                    "Optional explicit values for the preset's template variables, e.g. "
                    '{"commodity": "copper", "horizon": "6 months"}. They override values '
                    "extracted from the prompt."
                ),
                "additionalProperties": {"type": "string"},
            },
        },
        "required": ["prompt"],
    }
    is_readonly = False
    repeatable = True  # loop.py dedups by tool name; each prompt is a distinct run (#42)

    def __init__(
        self,
        *,
        include_shell_tools: bool = False,
        event_callback: Any | None = None,
        session_id: str | None = None,
        cancel_event: Any | None = None,
    ) -> None:
        """Initialize the swarm launcher.

        Args:
            include_shell_tools: Whether worker registries may include shell
                execution tools requested by presets.
            event_callback: Optional session event bridge used by the web chat.
            session_id: Session that owns this call. Used to index the run so a
                later user stop from the same session can still reach it.
            cancel_event: Cancellation flag shared with the hosting AgentLoop.
                Polled while waiting on the run so a user stop ends the wait
                instead of leaving the tool blocked for the whole budget.
        """
        self.include_shell_tools = include_shell_tools
        self._event_callback = event_callback
        self._session_id = session_id
        self._cancel_event = cancel_event

    def _emit_session_event(self, event_type: str, data: dict[str, Any]) -> None:
        """Forward swarm status to the hosting session SSE channel if present."""
        if self._event_callback is None:
            return
        try:
            self._event_callback(event_type, data)
        except Exception:
            logger.warning("Failed to forward %s to session event stream", event_type, exc_info=True)

    def execute(self, **kwargs: Any) -> str:
        """Start a swarm run: auto-match preset, extract variables, wait for completion.

        Args:
            **kwargs: Must include prompt (str). Optional preset_name (str) and
                variables (dict) overrides for the preset's template variables.

        Returns:
            JSON string with status, preset, variables, final_report, tasks, token_usage.
        """
        prompt = kwargs.get("prompt", "")

        if not prompt:
            return json.dumps(
                {"status": "error", "error": "Missing 'prompt' parameter"},
                ensure_ascii=False,
            )

        preset, preset_error = _resolve_preset(prompt, kwargs.get("preset_name"))
        if preset_error:
            return json.dumps(
                {"status": "error", "error": preset_error},
                ensure_ascii=False,
            )
        assert preset is not None
        variables, variables_error = _merge_variables(_build_variables(preset, prompt), kwargs.get("variables"))
        if variables_error:
            return json.dumps(
                {"status": "error", "error": variables_error},
                ensure_ascii=False,
            )

        logger.info(
            "SwarmTool: resolved preset=%s, variables=%s from prompt: %s",
            preset,
            variables,
            prompt[:100],
        )

        from src.config import load_swarm_agent_config
        from src.swarm.runtime import SwarmRuntime, register_active_run, unregister_active_run
        from src.swarm.store import SwarmStore, swarm_runs_root

        swarm_base_dir = swarm_runs_root()
        swarm_base_dir.mkdir(parents=True, exist_ok=True)
        store = SwarmStore(base_dir=swarm_base_dir)
        # Boot-time / operator-trusted: even when reached via the in-process
        # agent tool, the config path is resolved from disk / env, never from
        # the calling LLM's prompt (R-06).
        agent_config = load_swarm_agent_config()
        from src.config.accessor import get_env_config

        runtime = SwarmRuntime(
            store=store,
            max_workers=get_env_config().swarm.swarm_max_workers,
            agent_config=agent_config,
        )

        pending_live_events: list[dict[str, Any]] = []
        run_id_holder: dict[str, str | None] = {"run_id": None}

        try:
            def _live_callback(event: Any) -> None:
                payload = event.model_dump()
                current_run_id = run_id_holder["run_id"]
                if current_run_id is None:
                    pending_live_events.append(payload)
                    return
                self._emit_session_event(
                    "swarm.event",
                    {"run_id": current_run_id, "event": payload},
                )

            run = runtime.start_run(
                preset,
                variables,
                live_callback=_live_callback if self._event_callback is not None else None,
                include_shell_tools=self.include_shell_tools,
            )
        except FileNotFoundError as exc:
            return json.dumps(
                {"status": "error", "error": f"Preset not found: {exc}"},
                ensure_ascii=False,
            )
        except ValueError as exc:
            return json.dumps(
                {"status": "error", "error": f"Invalid DAG: {exc}"},
                ensure_ascii=False,
            )
        except Exception as exc:
            return json.dumps(
                {"status": "error", "error": f"Failed to start swarm: {exc}"},
                ensure_ascii=False,
            )

        run_id = run.id
        run_id_holder["run_id"] = run_id
        logger.info("SwarmTool: started run %s (preset=%s)", run_id, preset)
        self._emit_session_event(
            "swarm.started",
            {
                "run_id": run_id,
                "preset": preset,
                "variables": variables,
                "status": run.status.value,
                "agents": [agent.model_dump() for agent in run.agents],
                "tasks": [task.model_dump() for task in run.tasks],
            },
        )
        for event_payload in pending_live_events:
            self._emit_session_event(
                "swarm.event",
                {"run_id": run_id, "event": event_payload},
            )
        pending_live_events.clear()

        t0 = time.monotonic()
        max_wait = _max_wait_seconds()
        # Index the run so a user stop arriving after this call returns (budget
        # exhausted, or from the HTTP cancel endpoint holding a different
        # runtime) can still reach it.
        if self._session_id is not None:
            register_active_run(run_id, self._session_id, lambda: runtime.cancel_run(run_id))
        # Only a terminal run leaves the index. On the timeout path the worker
        # threads are still alive, so dropping the entry there would make a
        # later user stop unable to reach them.
        settled = False
        try:
            while time.monotonic() - t0 < max_wait:
                if self._cancel_event is not None:
                    # wait() returns as soon as the flag is set, so a stop does
                    # not have to sit out the poll interval.
                    if self._cancel_event.wait(_POLL_INTERVAL_SECONDS):
                        settled = True
                        return self._stop_cancelled_run(
                            runtime, store, run_id, preset, variables
                        )
                else:
                    time.sleep(_POLL_INTERVAL_SECONDS)

                loaded = store.load_run(run_id)
                if loaded is None:
                    settled = True
                    return json.dumps(
                        {"status": "error", "error": f"Run {run_id} disappeared"},
                        ensure_ascii=False,
                    )

                reconciled = store.reconcile_run(loaded, write=True)
                if reconciled.status.value in ("completed", "failed", "cancelled"):
                    settled = True
                    return _format_result(reconciled, preset, variables)

            # Wait budget elapsed but the run is still in flight. Do NOT cancel —
            # the daemon thread keeps working and the agent can decide to wait
            # more (re-invoke with the returned run_id) or hand off partial state
            # to the user. Cancelling here used to throw away minutes of LLM cost
            # whenever a preset legitimately ran past the budget.
            loaded = store.load_run(run_id)
            if loaded is not None:
                return _format_result(
                    store.reconcile_run(loaded, write=True), preset, variables, timed_out=True
                )

            return json.dumps(
                {"status": "timeout", "error": f"Swarm run {run_id} timed out after {max_wait}s"},
                ensure_ascii=False,
            )
        finally:
            if settled:
                unregister_active_run(run_id)

    def _stop_cancelled_run(
        self,
        runtime: Any,
        store: Any,
        run_id: str,
        preset: str,
        variables: dict[str, str],
    ) -> str:
        """Stop a run after a user cancel and report its terminal state.

        The runtime owns the per-run cancel event; signalling it makes workers
        mark their tasks ``cancelled`` instead of failing, so the persisted run
        stays internally consistent (and resumable) rather than looking crashed.
        """
        runtime.cancel_run(run_id)
        self._emit_session_event(
            "swarm.cancelled",
            {"run_id": run_id, "reason": "user_cancelled"},
        )

        deadline = time.monotonic() + _CANCEL_SETTLE_SECONDS
        loaded = store.load_run(run_id)
        while loaded is not None and loaded.status.value not in (
            "completed",
            "failed",
            "cancelled",
        ):
            if time.monotonic() >= deadline:
                break
            time.sleep(_POLL_INTERVAL_SECONDS)
            loaded = store.load_run(run_id)

        if loaded is None:
            return json.dumps(
                {"status": "cancelled", "cancelled_by_user": True, "run_id": run_id},
                ensure_ascii=False,
            )

        settled = store.reconcile_run(loaded, write=True)
        if settled.status.value in ("completed", "failed", "cancelled"):
            return _format_result(settled, preset, variables, cancelled_by_user=True)

        # The cancel flag is set but a worker was mid-LLM-call when the settle
        # window closed. Report what we know instead of claiming a terminal
        # state the store does not have.
        return json.dumps(
            {
                "status": "cancelling",
                "cancelled_by_user": True,
                "run_id": run_id,
                "preset": preset,
                "auto_variables": variables,
            },
            ensure_ascii=False,
        )


def _format_result(
    run: Any,
    preset: str,
    variables: dict[str, str],
    timed_out: bool = False,
    cancelled_by_user: bool = False,
) -> str:
    """Format a SwarmRun into a JSON result string.

    Args:
        run: SwarmRun instance.
        preset: Matched preset name.
        variables: Extracted variables.
        timed_out: Whether the run was terminated due to timeout.
        cancelled_by_user: Whether the user stopped the run before it finished.

    Returns:
        JSON string with run status, report, task summaries, and token usage.
    """
    from src.swarm.serialization import run_level_error, serialize_task

    task_summaries = [serialize_task(task) for task in run.tasks]

    # ``timed_out`` only means the SwarmTool's wait budget elapsed — the run
    # itself is still progressing in the background. Surface the run's real
    # status so a downstream agent can re-invoke with the run_id (or end its
    # turn with a "still working" message) instead of treating it as failure.
    result = {
        "status": run.status.value,
        "wait_budget_exhausted": timed_out,
        "cancelled_by_user": cancelled_by_user,
        "run_id": run.id,
        "preset": preset,
        "auto_variables": variables,
        "final_report": run.final_report or "",
        "error": run_level_error(run),
        "tasks": task_summaries,
        "token_usage": {
            "total_input_tokens": run.total_input_tokens,
            "total_output_tokens": run.total_output_tokens,
            "token_source": run.token_source,
        },
    }
    return json.dumps(result, ensure_ascii=False, indent=2)


def __getattr__(name: str):
    if name == "_MAX_WAIT_SECONDS":
        return _max_wait_seconds()
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")