"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""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}")