Download src/polyhedra/agents/coordinator.py from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 55.1 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/src/polyhedra/agents/coordinator.py
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/src/polyhedra/agents/coordinator.py
-
curl -L -o coordinator.py https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/src/polyhedra/agents/coordinator.py
55.1 kB
"""Coordinator agent β Orchestrator.
The Coordinator is always active. It is the entry point for every message:
it parses @mentions, routes tasks to agents or the human, maintains the
Research State, fires checkpoint gates, and detects @mention loops.
V4.3: Routing now goes through the EventBus. The Coordinator publishes
``AgentCompletedEvent`` / ``AgentBlockedEvent`` / ``HumanInputRequiredEvent``
after each agent run and reacts to them via subscribed handlers. Depth
tracking has moved into ``on_agent_completed``.
This module also exposes the top-level ``CoordinatorService`` which drives an
entire session (CLI or Slack webhook).
"""
from __future__ import annotations
import asyncio
import logging
import re
import time
from dataclasses import dataclass, field
from typing import Any, Callable, Awaitable
from polyhedra.agents.base import Agent, AgentResponse, Mention
from polyhedra.agents.quant.market_scope import V6_MARKETS
from polyhedra.core.agent_router import AgentRouter, QUANT_ROLES as _QUANT_ROLES, ALT_AGENT_MAP as _ALT_AGENT_MAP
from polyhedra.core.cache import SharedCache
from polyhedra.core.cost_gate import CostGate
from polyhedra.core.eventbus import (
EventBus, get_bus, clear_bus,
AgentCompletedEvent, AgentBlockedEvent,
HumanInputRequiredEvent, PortfolioAlertEvent,
)
from polyhedra.core.mention_parser import MentionParser
from polyhedra.core.research_state import ResearchStateManager, Paper, Gap, Decision, Hypothesis
from polyhedra.core.role_registry import RoleRegistry, RoleEntry, HELD_BY_AGENT, HELD_BY_HUMAN
from polyhedra.core.session import Session
from polyhedra.core.state_patcher import StatePatcher
from polyhedra.core.template_builder import TemplateBuilder, render_help_slack
from polyhedra.core.trace_logger import TraceLogger
from polyhedra.core.yolo_context import (
YoloRunContext,
mark_yolo_run_completed,
prepare_yolo_run_context,
)
from polyhedra.services.file_writer import FileWriter
from polyhedra.services.llm_service import LLMService
from polyhedra.services.rag_service import RAGService
logger = logging.getLogger(__name__)
# Re-export for backward compatibility with existing code that imports from here
_MAX_MENTION_DEPTH = 3
_COST_APPROVAL_THRESHOLD = 0.50
# Short labels used in YOLO progress status message (V5.0)
_ROLE_LABELS: dict[str, str] = {
"datafetcher": "DataFetcher",
"trendanalyst": "TrendAnalyst",
"sentimentanalyst": "SentimentAnalyst",
"marketeventwatcher": "MarketEventWatcher",
"optionsflowwatcher": "OptionsFlowWatcher",
"macrocontextwatcher": "MacroContextWatcher",
"unusualeventdetector": "UnusualEventDetector",
"eventrouter": "EventRouter",
"btcanalyst": "BTCAnalyst",
"spyanalyst": "SPYAnalyst",
"qqqanalyst": "QQQAnalyst",
"gldanalyst": "GLDAnalyst",
"quantresearcher": "QuantResearcher",
"backtester": "Backtester",
"riskanalyst": "RiskAnalyst",
"quantstrategist": "QuantStrategist",
"publisher": "Finley",
}
_V5_QUANT_PATH: list[str] = [
"datafetcher",
"trendanalyst",
"sentimentanalyst",
"quantresearcher",
"backtester",
"riskanalyst",
"quantstrategist",
"publisher",
]
_V6_WATCHER_PATH: list[str] = [
"datafetcher",
"trendanalyst",
"marketeventwatcher",
"optionsflowwatcher",
"macrocontextwatcher",
"unusualeventdetector",
"eventrouter",
]
_V6_ASSET_ROLE: dict[str, str] = {
"BTC": "btcanalyst",
"SPY": "spyanalyst",
"QQQ": "qqqanalyst",
"GLD": "gldanalyst",
}
_V6_DOWNSTREAM_PATH: list[str] = [
"quantresearcher",
"backtester",
"riskanalyst",
"quantstrategist",
"publisher",
]
_TYPED_AGENT_ROLES: dict[str, str] = {
"DataFetcher": "datafetcher",
"OptionsFlowWatcher": "optionsflowwatcher",
"TrendAnalyst": "trendanalyst",
"SentimentAnalyst": "sentimentanalyst",
"MarketEventWatcher": "marketeventwatcher",
"MacroContextWatcher": "macrocontextwatcher",
"UnusualEventDetector": "unusualeventdetector",
"EventRouter": "eventrouter",
"BTCAnalyst": "btcanalyst",
"SPYAnalyst": "spyanalyst",
"QQQAnalyst": "qqqanalyst",
"GLDAnalyst": "gldanalyst",
"QuantResearcher": "quantresearcher",
"Backtester": "backtester",
"RiskAnalyst": "riskanalyst",
"QuantStrategist": "quantstrategist",
"Publisher": "publisher",
"VizAgent": "vizagent",
"PortfolioMonitor": "portfoliomonitor",
}
def _is_llm_unavailable_output(content: str) -> bool:
lowered = content.lower()
return (
"llm unavailable" in lowered
or "llm service is unavailable" in lowered
or "llm service is not available" in lowered
or "llm unavailable β fallback" in lowered
)
def _extract_goal_tickers(text: str) -> list[str]:
"""Extract V6 market symbols from Slack-visible goals."""
tokens = re.findall(r"\b([A-Za-z]{1,5})\b", text)
seen: list[str] = []
for token in tokens:
normalized = token.upper()
if normalized in V6_MARKETS and normalized not in seen:
seen.append(normalized)
return seen
def _planned_quant_path(goal: str) -> tuple[str, list[str]]:
"""Return the Slack-visible quant path implied by the current goal."""
v6_tickers = _extract_goal_tickers(goal)
if v6_tickers:
asset_roles = [_V6_ASSET_ROLE[ticker] for ticker in v6_tickers if ticker in _V6_ASSET_ROLE]
return "V6 specialized quant path", _V6_WATCHER_PATH + asset_roles + _V6_DOWNSTREAM_PATH
return "V5 general quant path", _V5_QUANT_PATH
def _next_planned_quant_role(goal: str, current_role: str) -> str | None:
"""Return the next PRD workflow node after *current_role*, if any."""
_, planned_roles = _planned_quant_path(goal)
try:
current_index = planned_roles.index(current_role)
except ValueError:
return None
if current_index + 1 >= len(planned_roles):
return None
return planned_roles[current_index + 1]
class _CostRejected(Exception):
"""Sentinel raised when the user declines a cost-gated operation."""
@dataclass
class CheckpointResult:
"""Result of a human checkpoint gate."""
approved: bool
response: str = "" # "yes" | "adjust" | "stop" | free-text
# Backward-compatible module-level helper β delegates to TemplateBuilder
_template_builder = TemplateBuilder()
def _build_input_templates(
touchpoint: str,
*,
next_role: str | None = None,
proposal_id: str | None = None,
session_id: str | None = None,
) -> str:
"""Build ranked, pre-filled input templates (delegates to TemplateBuilder)."""
return _template_builder.build(
touchpoint,
next_role=next_role,
proposal_id=proposal_id,
session_id=session_id,
)
class CoordinatorAgent(Agent):
"""
Orchestration agent β always active, never deselected.
Responsibilities (from FR-010):
- Parse all @mentions and route tasks
- Track which roles are human vs. agent
- Maintain and update the Research State
- Trigger and manage checkpoints
- Detect and break @mention loops
- Post cost estimates before high-token operations
- Log all agent actions with timestamps
"""
name = "Coordinator"
role = "coordinator"
role_title = "Quant Coordinator"
system_prompt = (
"You are Coordinator for a collaborative paper-trading analysis team. "
"You orchestrate quant agents, manage checkpoints, and keep the analysis on track. "
"You are concise, structured, and always transparent about what is happening next."
)
def __init__(self) -> None:
super().__init__()
self._mention_depth: dict[str, int] = {} # tracks chain depth per originating message
async def can_handle(self, mention: Mention) -> bool:
return mention.mentioned_role == self.role
async def handle(
self,
mention: Mention,
thread_context: list[dict[str, Any]],
research_state: dict[str, Any],
) -> AgentResponse:
content = (
f"π **Coordinator** β received your message.\n\n"
f"Active roles: _{mention.content}_\n\n"
"How can I help? You can:\n"
"- `/poly state` to see the Research State\n"
"- `/poly export` to export all artifacts\n"
"- `/poly role <name> human` to take over a role\n"
"- @mention any agent directly to assign a task"
)
return AgentResponse(agent_role=self.role, content=content)
# --------------------------------------------------------------------------- #
# Coordinator Service β drives the full session loop
# --------------------------------------------------------------------------- #
PostFn = Callable[[str, str], Awaitable[None]] # (from_role, content) -> None
CheckpointFn = Callable[[str], Awaitable[CheckpointResult]] # summary -> result
YoloUpdateFn = Callable[[str], Awaitable[None]] # new_content -> None
class CoordinatorService:
"""
High-level orchestration service for a Polyhedra session.
The ``dispatch`` method is the single entry point: it receives a raw
message, parses @mentions, routes them to agents (or the human when they
hold a role), enforces loop limits, fires checkpoint gates, and updates
the Research State.
Usage::
service = CoordinatorService(session=session, post_fn=..., checkpoint_fn=...)
await service.dispatch(from_role="human", text="@datafetcher fetch SPY")
"""
def __init__(
self,
session: Session,
post_fn: PostFn,
checkpoint_fn: CheckpointFn,
llm_service: LLMService | None = None,
mode: str = "investigation",
yolo_update_fn: "YoloUpdateFn | None" = None,
) -> None:
self.session = session
self._post = post_fn
self._checkpoint = checkpoint_fn
self._llm = llm_service
self._mode = mode
self._yolo_update_fn = yolo_update_fn
self._yolo_completed: list[str] = [] # agents finished in this YOLO run
self._yolo_run_context: YoloRunContext | None = None
self._typed_yolo_run_started = False
self._typed_yolo_states: dict[str, str] = {}
self._typed_yolo_times: dict[str, dict[str, str]] = {}
self._parser = MentionParser(session.registry)
# V4.4 STRUCT-1: delegate to focused sub-components
self._router = AgentRouter()
self._templates = TemplateBuilder()
self._patcher = StatePatcher()
self._cost_gate = CostGate()
# V4.4 STRUCT-3: trace logger (FR-S3.4 β trace.jsonl in session dir)
self._trace = TraceLogger(session.session_dir)
# V4.3 infrastructure
self._cache = SharedCache()
self._cache.warm_from_disk(session.session_dir)
# V4.4 FIX-1: pass session_id so RAGService uses a session-scoped embeddings
# path, preventing cross-session index collisions (FR-1.2).
self._rag = RAGService(session.session_dir, session_id=session.session_id)
self._rag.rebuild_artifact_index_from_disk(session.session_dir)
self._bus = get_bus(session.session_id)
self._bus.subscribe(AgentCompletedEvent, self._on_agent_completed)
self._bus.subscribe(AgentBlockedEvent, self._on_agent_blocked)
self._bus.subscribe(HumanInputRequiredEvent, self._on_human_input_required)
self._bus.subscribe(PortfolioAlertEvent, self._on_portfolio_alert)
# ------------------------------------------------------------------ #
# Public API
# ------------------------------------------------------------------ #
def prepare_yolo_run(self, tickers: list[str] | None = None) -> YoloRunContext:
"""Prepare shared V7 YOLO run context for this session."""
self._yolo_completed = []
self._yolo_run_context = prepare_yolo_run_context(
self.session.session_dir,
tickers=tickers,
)
return self._yolo_run_context
async def run_yolo(self, tickers: list[str]) -> Any:
"""Run the shared typed quant graph and post Finley's product output."""
from datetime import UTC, datetime
from polyhedra.core.active_routing import build_active_routing_plan
from polyhedra.core.dependency_executor import AgentExecutionState
from polyhedra.core.quant_contracts import ExecutionContext
from polyhedra.services.quant_runtime import QuantRuntime
if not tickers:
raise ValueError("YOLO requires at least one ticker")
if self._yolo_run_context is None or self._typed_yolo_run_started:
self.prepare_yolo_run(tickers)
context = self._yolo_run_context
if context is None:
raise RuntimeError("YOLO run context was not created")
self._typed_yolo_run_started = True
plan = build_active_routing_plan(
run_id=context.run_id,
execution_context=ExecutionContext.YOLO,
tickers=tickers,
)
self._typed_yolo_states = {
item.agent: AgentExecutionState.WAITING.value for item in plan.active_agents
}
self._typed_yolo_times = {item.agent: {} for item in plan.active_agents}
agents = {}
for item in plan.active_agents:
role = _TYPED_AGENT_ROLES[item.agent]
entry = self.session.registry.get(role)
if entry is None or entry.is_human:
raise RuntimeError(f"@{role} is not available for the automated YOLO run")
agents[item.agent] = entry.agent
writer = FileWriter(
self.session.session_dir,
session_id=self.session.session_id,
cache=self._cache,
rag=self._rag,
)
async def progress(agent, state, detail: str) -> None:
self._typed_yolo_states[agent] = state.value
timestamp = datetime.now(tz=UTC).isoformat()
if state == AgentExecutionState.RUNNING:
self._typed_yolo_times[agent]["started_at"] = timestamp
elif state in {
AgentExecutionState.COMPLETED,
AgentExecutionState.FAILED,
AgentExecutionState.BLOCKED,
}:
self._typed_yolo_times[agent]["finished_at"] = timestamp
if state == AgentExecutionState.COMPLETED:
role = _TYPED_AGENT_ROLES[agent]
if role not in self._yolo_completed:
self._yolo_completed.append(role)
if self._yolo_update_fn is not None:
await self._yolo_update_fn(self._build_typed_yolo_status(tickers, detail))
async def before_agent(agent, inputs) -> None:
await self._maybe_gate_typed_cost(agent, inputs.model_dump_json())
runtime = QuantRuntime(
session_dir=self.session.session_dir,
session_id=self.session.session_id,
agents=agents,
writer=writer,
trace=self._trace,
progress=progress,
before_agent=before_agent,
)
result = await runtime.run_yolo(
run_id=context.run_id,
tickers=tickers,
started_at=datetime.fromisoformat(context.run_started_at),
)
await self._cache.async_flush_to_disk(self.session.session_dir)
if result.finley is not None:
content = result.finley.payload.slack_rendering
await self._post("publisher", content)
self.session.post("publisher", content)
else:
failures = [
record for record in result.record.execution.records
if record.state != AgentExecutionState.COMPLETED
]
detail = "\n".join(
f"- {record.agent}: {record.state.value}"
+ (f" ({record.error})" if record.error else "")
+ (f" (blocked by {', '.join(record.blocked_by)})" if record.blocked_by else "")
for record in failures
)
message = (
"YOLO analysis did not reach Finley. No market opinion was produced.\n\n"
f"{detail or '- Publisher output is unavailable.'}"
)
await self._post("coordinator", message)
self.session.post("coordinator", message)
if result.record.status.value == "completed":
mark_yolo_run_completed(self.session.session_dir)
return result
async def run_visualization(
self,
chart_type: str,
*,
ticker: str | None = None,
source_run_id: str | None = None,
) -> Any:
"""Run VizAgent on one frozen typed YOLO run through the governed runtime."""
from datetime import UTC, datetime
from polyhedra.agents.quant.product_contracts import ChartType
from polyhedra.core.artifacts import JsonArtifactRef
from polyhedra.core.yolo_context import allocate_quant_run_directory
from polyhedra.core.quant_contracts import ExecutionContext
from polyhedra.services.quant_run_record import (
QuantRunRecord, QuantRunRecordStore, QuantSupportRunRecordStore,
)
from polyhedra.services.quant_support_runtime import QuantSupportRuntime
requested = ChartType(chart_type.upper())
yolo_store = QuantRunRecordStore(
self.session.session_dir, session_id=self.session.session_id,
)
support_store = QuantSupportRunRecordStore(
self.session.session_dir, session_id=self.session.session_id,
)
if requested == ChartType.PORTFOLIO_PNL:
monitor_records = support_store.records(context=ExecutionContext.PORTFOLIO_MONITOR)
if source_run_id:
source = support_store.load(source_run_id)
if source.execution_context != ExecutionContext.PORTFOLIO_MONITOR:
raise ValueError("portfolio chart source is not a monitor run")
elif monitor_records:
source = max(monitor_records, key=lambda item: (item.completed_at, item.run_id))
else:
raise ValueError("Run PortfolioMonitor first; no typed portfolio source exists.")
elif source_run_id:
source = yolo_store.load(source_run_id)
else:
candidates = [
QuantRunRecord.model_validate(item)
for item in yolo_store.baseline_candidates()
if item.get("execution_context") == "YOLO" and item.get("status") == "completed"
]
if not candidates:
raise ValueError("Run YOLO first; VizAgent needs one completed typed source run.")
source = max(candidates, key=lambda item: (item.completed_at, item.run_id))
if ticker is not None:
ticker = ticker.upper()
if ticker not in source.ticker_scope:
raise ValueError(f"{ticker} is not in source run {source.run_id}.")
scope = [ticker]
else:
scope = list(source.ticker_scope)
producer = {
ChartType.CANDLESTICK: "DataFetcher",
ChartType.RSI_MACD: "DataFetcher",
ChartType.BACKTEST: "Backtester",
ChartType.RISK_HEATMAP: "RiskAnalyst",
ChartType.PORTFOLIO_PNL: "PortfolioMonitor",
}[requested]
references = [
ref for ref in source.artifact_inventory
if isinstance(ref, JsonArtifactRef)
and ref.producer == producer
and (
requested not in {ChartType.CANDLESTICK, ChartType.RSI_MACD}
or ref.path.endswith(f"/raw/{ticker}.json")
)
]
if not references:
raise ValueError(
f"Source run {source.run_id} has no typed {producer} artifact for {requested.value}."
)
entry = self.session.registry.get("vizagent")
if entry is None or entry.is_human:
raise RuntimeError("@vizagent is not available for automated visualization")
writer = FileWriter(
self.session.session_dir,
session_id=self.session.session_id,
cache=self._cache,
rag=self._rag,
)
runtime = QuantSupportRuntime(
session_dir=self.session.session_dir,
session_id=self.session.session_id,
agents={"VizAgent": entry.agent},
writer=writer,
trace=self._trace,
before_agent=self._maybe_gate_typed_cost,
)
result = await runtime.run_visualization(
run_id=allocate_quant_run_directory(self.session.session_dir),
ticker_scope=scope,
source_run_id=source.run_id,
source_artifacts=references,
chart_type=requested,
ticker=ticker,
started_at=datetime.now(tz=UTC),
)
await self._cache.async_flush_to_disk(self.session.session_dir)
if result.output is not None:
paths = [chart.image_ref.path for chart in result.output.payload.charts]
content = result.output.payload.caption
if paths:
content += "\n\n" + "\n".join(f"Chart: `{path}`" for path in paths)
if result.output.payload.errors:
content += "\n\n" + "\n".join(
f"Data gap: {item.message}" for item in result.output.payload.errors
)
await self._post("vizagent", content)
self.session.post("vizagent", content)
return result
async def run_portfolio_monitor(self, *, post_summary: bool = False) -> Any:
"""Run the separately initialized typed monitor and publish validated alerts."""
import os
from datetime import UTC, datetime
from polyhedra.agents.quant.portfoliomonitor import _is_market_hours
from polyhedra.agents.quant.product_contracts import (
MarketHoursState, MonitorThresholds, PaperPosition,
QuoteProviderConfiguration,
)
from polyhedra.core.yolo_context import allocate_quant_run_directory
from polyhedra.services.quant_support_runtime import QuantSupportRuntime
state = ResearchStateManager(self.session.session_dir).load()
quant = state.quant_state
open_positions = [
position for position in (quant.portfolio if quant else [])
if position.status == "open"
]
if not open_positions:
if post_summary:
await self._post("portfoliomonitor", "No open paper positions to monitor.")
return None
entry = self.session.registry.get("portfoliomonitor")
if entry is None or entry.is_human:
raise RuntimeError("@portfoliomonitor is not available for automated monitoring")
positions = [
PaperPosition(
position_id=position.position_id,
ticker=position.ticker,
direction=position.direction.upper(),
entry_price=float(position.entry_price),
size_percentage=float(position.size_pct),
)
for position in open_positions
]
threshold = float(os.environ.get("POLYHEDRA_ALERT_MOVE_PCT", "2.0"))
runtime = QuantSupportRuntime(
session_dir=self.session.session_dir,
session_id=self.session.session_id,
agents={"PortfolioMonitor": entry.agent},
writer=FileWriter(
self.session.session_dir,
session_id=self.session.session_id,
cache=self._cache,
rag=self._rag,
),
trace=self._trace,
)
result = await runtime.run_portfolio_monitor(
run_id=allocate_quant_run_directory(self.session.session_dir),
ticker_scope=list(dict.fromkeys(position.ticker for position in positions)),
positions=positions,
thresholds=MonitorThresholds(
stop_loss_percentage=threshold,
take_profit_percentage=threshold,
),
paused=bool(quant.monitor_paused if quant else False),
market_hours=(
MarketHoursState.OPEN
if _is_market_hours(getattr(entry.agent, "_market_tz", "America/New_York"))
else MarketHoursState.CLOSED
),
quote_provider=QuoteProviderConfiguration(
provider="finnhub",
configured=bool(os.environ.get("FINNHUB_API_KEY", "").strip()),
),
)
await self._cache.async_flush_to_disk(self.session.session_dir)
if result.output is not None:
output = result.output
for alert in output.payload.alerts:
content = (
f"Portfolio alert: {alert.ticker} {alert.alert_type.value}\n"
f"{alert.message}\n\n"
"Paper trading simulation only. No position was closed."
)
await self._post("portfoliomonitor", content)
self.session.post("portfoliomonitor", content)
if post_summary and not output.payload.alerts:
content = (
f"Portfolio monitor completed for {len(output.payload.position_checks)} "
"open paper position(s); no threshold alert was produced."
)
await self._post("portfoliomonitor", content)
self.session.post("portfoliomonitor", content)
return result
async def _maybe_gate_typed_cost(self, agent: str, prompt: str) -> None:
role = _TYPED_AGENT_ROLES[agent]
entry = self.session.registry.get(role)
llm = self._llm or (getattr(entry.agent, "_llm", None) if entry else None)
if llm is None:
return
input_tokens = llm.estimate_tokens(prompt)
estimated_cost = llm.calculate_cost(input_tokens, 1_024, None)
if not self._cost_gate.requires_approval(estimated_cost):
return
summary = self._cost_gate.format_approval_request(
estimated_cost,
f"@{role} ({input_tokens:,} input + 1,024 output tokens)",
)
result = await self._checkpoint(summary)
if not result.approved:
raise _CostRejected(f"@{role} cost approval was declined")
def _build_typed_yolo_status(self, tickers: list[str], detail: str = "") -> str:
grouped: dict[str, list[str]] = {
"RUNNING": [], "COMPLETED": [], "WAITING": [], "FAILED": [], "BLOCKED": [],
}
for agent, state in self._typed_yolo_states.items():
grouped.setdefault(state, []).append(agent)
lines = [
f"β‘ YOLO run in progress β {', '.join(tickers)}",
f" {self._yolo_mode_label()} | dependency-based agent execution",
]
for state, label in (
("RUNNING", "Running"), ("COMPLETED", "Completed"),
("WAITING", "Waiting"), ("FAILED", "Failed"), ("BLOCKED", "Blocked"),
):
if grouped[state]:
lines.append(f" {label}: {', '.join(grouped[state])}")
if detail and (grouped["FAILED"] or grouped["BLOCKED"]):
lines.append(f" Detail: {detail}")
if grouped["COMPLETED"] and not any(grouped[state] for state in ("RUNNING", "WAITING")):
lines[0] = f"β‘ YOLO run finished β {', '.join(tickers)}"
return "\n".join(lines)
async def dispatch(self, from_role: str, text: str, origin_id: str = "") -> None:
"""
Entry point for every incoming message.
Handles /poly slash commands first, then parses @mentions and routes.
"""
# V4.3: handle /poly commands before mention parsing
stripped = text.strip()
if stripped.startswith("/poly "):
handled = await self._handle_slash_command(stripped)
if handled:
return
msg = self.session.post(from_role=from_role, content=text)
if not origin_id:
origin_id = msg.message_id
self._router.init_origin(origin_id)
mentions = self._parser.parse(text, from_role=from_role)
if not mentions:
return
for mention in mentions:
if not self._router.can_dispatch(origin_id, mention.mentioned_role, self._mode):
if self._router.is_quant_role(mention.mentioned_role):
templates = _build_input_templates(
"checkpoint", next_role=mention.mentioned_role
)
await self._post(
"coordinator",
f"βΈ **Coordinator** β quant pipeline mid-chain checkpoint "
f"(depth {_MAX_MENTION_DEPTH} reached).\n\n"
f"Analysis so far is complete and has been saved. "
f"This is a natural human review point β check the quant artifacts before proceeding."
f"{templates}",
)
self._router.reset_depth(origin_id, mention.mentioned_role)
else:
await self._post(
"coordinator",
f"β **Coordinator** β @mention chain limit ({_MAX_MENTION_DEPTH}) reached. "
"Stopping to prevent loops. Please review the current thread and continue manually.",
)
return
self._router.record_dispatch(origin_id, mention.mentioned_role)
await self._route(mention, origin_id)
async def initialize_session(self, goal: str, selected_roles: list[str], human_roles: list[str]) -> None:
"""
Called at session start (/poly init).
Posts a welcome message, records the goal, and updates the Research State.
"""
self.session.goal = goal
self.session.save_meta()
state_manager = ResearchStateManager(self.session.session_dir)
state_manager.update(goal=goal)
held_roles = {r.lower() for r in human_roles}
for role_name in selected_roles:
entry = self.session.registry.get(role_name)
if entry and role_name.lower() in held_roles:
self.session.registry.take_over(role_name, HELD_BY_HUMAN)
workflow_name, _workflow_roles = _planned_quant_path(goal)
if self._mode == "yolo" and self._yolo_run_context is None:
self.prepare_yolo_run(_extract_goal_tickers(goal))
yolo_mode_label = self._yolo_mode_label()
welcome = [
"π **Polyhedra session started.**",
"",
f"**Goal:** {goal}",
f"**Workflow:** {workflow_name}",
]
if self._mode == "yolo":
welcome.append(
f"**Mode:** {yolo_mode_label} β live progress updates will track the run; "
"Finley posts the final output."
)
if held_roles:
welcome.append(f"**Roles held by you:** {', '.join(held_roles)}")
if self._mode != "yolo":
welcome += [
"",
"Type your quant analysis goal to begin, or @mention an agent directly.",
"_Example:_ `@datafetcher fetch SPY`",
]
await self._post("coordinator", "\n".join(welcome))
self.session.post("coordinator", "\n".join(welcome))
# ------------------------------------------------------------------ #
# Internal routing
# ------------------------------------------------------------------ #
async def _route(self, mention: Mention, origin_id: str) -> None:
# Inject session_dir so agents can read/write quant artifacts (V4.0 compat)
mention.metadata["session_dir"] = str(self.session.session_dir)
if self._mode == "yolo":
if self._yolo_run_context is None:
self.prepare_yolo_run(_extract_goal_tickers(self.session.goal))
if self._yolo_run_context is not None:
mention.metadata["yolo_run_mode"] = self._yolo_run_context.run_mode
mention.metadata["yolo_run_id"] = self._yolo_run_context.run_id
mention.metadata["yolo_run_started_at"] = self._yolo_run_context.run_started_at
entry = self.session.registry.get(mention.mentioned_role)
if entry is None:
await self._post(
"coordinator",
f"β οΈ **Coordinator** β @{mention.mentioned_role} is not an active role in this session.",
)
return
if entry.is_human:
templates = _build_input_templates("uncertainty", next_role=entry.role)
await self._post(
"coordinator",
f"π¨ **Coordinator** β @human (holding role *{entry.role}*): {mention.content}"
f"{templates}",
)
# Publish HumanInputRequiredEvent (FR-2.x)
self._bus.publish(HumanInputRequiredEvent(
session_id=self.session.session_id,
agent_role=entry.role,
question=mention.content,
content=f"Human input required for role *{entry.role}*",
))
return
# V4.3: inject FileWriter with SharedCache + RAGService (FR-1.1 β FR-3.1)
entry.agent.files = FileWriter(
self.session.session_dir,
session_id=self.session.session_id,
cache=self._cache,
rag=self._rag,
)
# V4.3: inject EventBus and TokenBudget into agent
entry.agent.bus = self._bus
# V4.4 STRUCT-3: inject TraceLogger (FR-S3.2)
entry.agent.trace = self._trace
# Cost estimation gate (NFR Β§5)
try:
await self._maybe_gate_cost(mention)
except _CostRejected:
return
# Run agent
thread_ctx = self.session.thread_history(last_n=20)
state = self.session.research_state.to_dict()
try:
response = await asyncio.wait_for(
entry.agent.handle(mention, thread_ctx, state),
timeout=90.0,
)
except asyncio.TimeoutError:
await self._post(
"coordinator",
f"β±οΈ **Coordinator** β @{entry.role} timed out (>90 s). Retrying onceβ¦",
)
try:
response = await asyncio.wait_for(
entry.agent.handle(mention, thread_ctx, state),
timeout=90.0,
)
except Exception as exc:
await self._post(
"coordinator",
f"β **Coordinator** β @{entry.role} failed after retry: {exc}",
)
return
except Exception as exc:
logger.exception("Agent %s raised an exception: %s", entry.role, exc)
await self._post(
"coordinator",
f"β **Coordinator** β @{entry.role} encountered an error: {exc}",
)
return
# Post agent response
# V5.0: in YOLO mode, suppress intermediate quant agent posts.
# publisher (Finley) always posts β it IS the YOLO output (FR-9.2 / FR-9.3).
is_suppressed = self._mode == "yolo" and entry.role in _QUANT_ROLES and entry.role != "publisher"
if not is_suppressed:
await self._post(entry.role, response.content)
self.session.post(entry.role, response.content)
# V4.3: determine current depth for the event
current_depth = self._router.current_depth(origin_id, mention.mentioned_role)
# V4.3: detect blocked state β publish AgentBlockedEvent
if response.content.startswith("Skipped β"):
blocked_role = response.mentions[0] if response.mentions else None
self._bus.publish(AgentBlockedEvent(
session_id=self.session.session_id,
agent_role=entry.role,
reason=response.content[:200],
missing_artifact=response.artifact_path,
suggested_role=blocked_role,
content=response.content,
))
return
if self._mode == "yolo" and entry.role in _QUANT_ROLES and _is_llm_unavailable_output(
response.content
):
self._bus.publish(AgentBlockedEvent(
session_id=self.session.session_id,
agent_role=entry.role,
reason=(
"LLM service is unavailable. YOLO requires real LLM agent reasoning; "
"fallback output is not a completed run."
),
missing_artifact=response.artifact_path,
suggested_role=None,
content=response.content,
))
return
# V4.3: publish AgentCompletedEvent β Coordinator's on_agent_completed
# handles state updates, checkpoint, and chaining (FR-2.1 / FR-2.3)
next_role = response.mentions[0] if response.mentions else None
event = AgentCompletedEvent(
session_id=self.session.session_id,
agent_role=entry.role,
artifact_path=response.artifact_path,
next_role=next_role,
reason="",
depth=current_depth,
content=response.content,
updates_state=response.updates_state,
state_patch=response.state_patch,
checkpoint_required=response.checkpoint_required,
checkpoint_summary=response.checkpoint_summary,
origin_id=origin_id,
)
self._bus.publish(event)
async def _maybe_gate_cost(self, mention: Mention) -> None:
"""
If LLMService is configured and the estimated cost of running this
agent exceeds _COST_APPROVAL_THRESHOLD, post an estimate and await
human approval via the checkpoint function (NFR Β§5).
"""
if self._llm is None:
return
# Build a rough prompt to estimate against: the mention content +
# the last 20 thread messages + the Research State.
state_md = self.session.research_state.to_markdown()
thread_preview = "\n".join(
f"{m['from_role']}: {m['content'][:200]}"
for m in self.session.thread_history(last_n=20)
)
rough_prompt = f"{state_md}\n\n{thread_preview}\n\n{mention.content}"
input_tokens = self._llm.estimate_tokens(rough_prompt)
# Conservative output estimate: 1 024 tokens
output_tokens = 1_024
model = None # uses LLMService default
estimated_cost = self._llm.calculate_cost(input_tokens, output_tokens, model)
if self._cost_gate.requires_approval(estimated_cost):
summary = self._cost_gate.format_approval_request(
estimated_cost,
f"@{mention.mentioned_role} ({input_tokens:,} input + {output_tokens:,} output tokens)",
)
result = await self._checkpoint(summary)
if not result.approved:
await self._post(
"coordinator",
f"βΈ **Coordinator** β @{mention.mentioned_role} operation cancelled "
"due to cost. Adjust the scope and try again.",
)
raise _CostRejected
def _apply_state_update(self, response: AgentResponse) -> None:
"""Patch the Research State from agent response metadata."""
manager = ResearchStateManager(self.session.session_dir)
current = manager.load()
papers_raw = response.metadata.get("papers", [])
if papers_raw:
papers = [
Paper(
title=p.get("title", "Unknown"),
paper_id=p.get("paperId", "") or p.get("paper_id", ""),
year=p.get("year"),
relevance_score=float(p.get("relevanceScore") or p.get("citationCount") or 0),
one_line_summary=(p.get("abstract") or "")[:100],
bibtex_key=(p.get("title", "").split()[0].lower() if p.get("title") else ""),
)
for p in papers_raw
]
current.key_papers = papers
pending_task = response.metadata.get("pending_task")
if pending_task and pending_task not in current.pending_tasks:
current.pending_tasks.append(pending_task)
current = manager.load()
papers_raw = response.metadata.get("papers", [])
if papers_raw:
papers = [
Paper(
title=p.get("title", "Unknown"),
paper_id=p.get("paperId", "") or p.get("paper_id", ""),
year=p.get("year"),
relevance_score=float(p.get("relevanceScore") or p.get("citationCount") or 0),
one_line_summary=(p.get("abstract") or "")[:100],
bibtex_key=(p.get("title", "").split()[0].lower() if p.get("title") else ""),
)
for p in papers_raw
]
current.key_papers = papers
pending_task = response.metadata.get("pending_task")
if pending_task and pending_task not in current.pending_tasks:
current.pending_tasks.append(pending_task)
current.compress()
manager.save(current)
# ------------------------------------------------------------------ #
# V4.3 EventBus handlers (FR-2.x)
# ------------------------------------------------------------------ #
async def _on_agent_completed(self, event: AgentCompletedEvent) -> None:
"""
React to an agent completing β state update, checkpoint, chain to next.
Depth tracking lives here (FR-2.3). EventBus schedules this as a task.
"""
# State update β delegated to StatePatcher (STRUCT-1 FR-S1.3)
if event.updates_state and event.state_patch:
self._patcher.apply(self.session.session_dir, event.state_patch)
# V5.0: in YOLO mode update the pipeline status message instead of posting
if self._mode == "yolo" and event.agent_role in _QUANT_ROLES:
self._yolo_completed.append(event.agent_role)
if event.agent_role == "publisher":
mark_yolo_run_completed(self.session.session_dir)
if self._yolo_update_fn is not None:
await self._yolo_update_fn(
self._build_yolo_status(event.agent_role, done=True)
)
# Checkpoint gate β skipped entirely in YOLO mode (FR-9.2)
if event.checkpoint_required and self._mode != "yolo":
result = await self._checkpoint(event.checkpoint_summary)
if not result.approved:
await self._post(
"coordinator",
"βΈ **Coordinator** β session paused at user's request. "
"Resume anytime with `/poly resume` or by continuing in the thread.",
)
return
# Async flush cache to disk (FR-1.2)
await self._cache.async_flush_to_disk(self.session.session_dir)
# Chain to next agent. In YOLO mode, upstream "human" routing means
# "no trade / needs review"; continue to the next PRD agent so Finley
# can publish the final readable outcome.
next_role = event.next_role
if self._mode == "yolo" and next_role == "human" and event.agent_role != "publisher":
next_role = _next_planned_quant_role(self.session.goal, event.agent_role)
if next_role:
logger.info(
"YOLO: converted @%s -> @human routing into @%s",
event.agent_role,
next_role,
)
if next_role:
follow_up = Mention(
mentioned_role=next_role,
from_role=event.agent_role,
content=f"continue β previous: {event.content[:200]}",
)
await self._route(follow_up, event.origin_id)
def _build_yolo_status(self, latest_role: str, *, done: bool) -> str:
"""Build the YOLO progress status message content (FR-9.2)."""
v6_roles = {
"marketeventwatcher", "optionsflowwatcher", "macrocontextwatcher",
"unusualeventdetector", "eventrouter", "btcanalyst", "spyanalyst",
"qqqanalyst", "gldanalyst",
}
workflow_name, planned_roles = _planned_quant_path(self.session.goal)
if workflow_name.startswith("V6"):
_PIPELINE = planned_roles
elif latest_role in v6_roles or any(role in v6_roles for role in self._yolo_completed):
asset_roles = [
role for role in ("btcanalyst", "spyanalyst", "qqqanalyst", "gldanalyst")
if role == latest_role or role in self._yolo_completed
]
_PIPELINE = [
"marketeventwatcher",
"optionsflowwatcher",
"macrocontextwatcher",
"unusualeventdetector",
"eventrouter",
*asset_roles,
"quantresearcher",
"backtester",
"riskanalyst",
"quantstrategist",
"publisher",
]
else:
_PIPELINE = [
"datafetcher", "trendanalyst", "sentimentanalyst",
"quantresearcher", "backtester", "riskanalyst",
"quantstrategist", "publisher",
]
parts: list[str] = []
for role in _PIPELINE:
if role in self._yolo_completed:
parts.append(f"β
{_ROLE_LABELS.get(role, role)}")
elif role == latest_role and not done:
parts.append(f"β³ {_ROLE_LABELS.get(role, role)}β¦")
elif role not in self._yolo_completed:
parts.append(f"βͺ {_ROLE_LABELS.get(role, role)}")
steps = " β ".join(parts)
yolo_mode_label = self._yolo_mode_label()
if latest_role == "publisher" or "publisher" in self._yolo_completed:
return (
f"β‘ YOLO run complete β {self.session.goal}\n"
f" {workflow_name} | {yolo_mode_label}\n"
f" {steps}\n"
" Finley's post is ready below."
)
return (
f"β‘ YOLO run in progress β {self.session.goal}\n"
f" {workflow_name} | {yolo_mode_label}\n"
f" {steps}"
)
def _yolo_mode_label(self) -> str:
"""Return a Slack/UI-friendly YOLO run mode label."""
try:
qs = ResearchStateManager(self.session.session_dir).load().quant_state
except Exception:
qs = None
mode = getattr(qs, "yolo_run_mode", "") if qs is not None else ""
if mode == "session_delta":
return "Session-delta YOLO"
if mode == "baseline":
return "Baseline YOLO"
yolo_run_context = getattr(self, "_yolo_run_context", None)
if yolo_run_context is not None:
return yolo_run_context.label
return "YOLO"
async def _on_agent_blocked(self, event: AgentBlockedEvent) -> None:
"""React to an agent blocked on missing data (FR-2.x / FR-9.3 V5.0).
Always posts regardless of YOLO mode β blocked events bypass suppression.
"""
# V5.0: in YOLO mode, prepend an interrupted banner
yolo_header = ""
if self._mode == "yolo":
yolo_header = (
f"β‘ YOLO run interrupted β {self.session.goal} | {self._yolo_mode_label()}\n"
)
templates = _build_input_templates("agent_blocked", next_role=event.suggested_role)
await self._post(
"coordinator",
f"{yolo_header}β οΈ **Coordinator** β @{event.agent_role} is blocked: {event.reason}"
f"{templates}",
)
if event.suggested_role:
follow_up = Mention(
mentioned_role=event.suggested_role,
from_role=event.agent_role,
content=f"provide missing data: {event.missing_artifact or 'unknown artifact'}",
)
await self._route(follow_up, "")
async def _on_human_input_required(self, event: HumanInputRequiredEvent) -> None:
"""React to an agent requesting human input. Already posted β no-op."""
async def _on_portfolio_alert(self, event: PortfolioAlertEvent) -> None:
"""React to a portfolio threshold breach (FR-2.4) β independent of running chain."""
await self._post("portfoliomonitor", event.content)
# ------------------------------------------------------------------ #
# V4.3 slash command handler
# ------------------------------------------------------------------ #
async def _handle_slash_command(self, text: str) -> bool:
"""
Handle /poly V4.3 commands. Returns True if the command was consumed.
New in V4.3:
/poly cache clear β flush session cache, reload from disk on next access
/poly cache status β show hit/miss stats
/poly tokens β show session token usage by agent
"""
parts = text.strip().split()
if len(parts) < 2 or parts[0] != "/poly":
return False
sub = parts[1].lower()
if sub == "cache" and len(parts) >= 3:
action = parts[2].lower()
if action == "clear":
self._cache.clear()
await self._post(
"coordinator",
"β
**Coordinator** β session cache cleared. "
"Next artifact read will reload from disk.",
)
return True
if action == "status":
stats = self._cache.stats.to_dict()
entry_count = len(self._cache._store)
await self._post(
"coordinator",
f"π **Cache status**\n\n"
f"- Entries in memory: {entry_count}\n"
f"- Hits: {stats['hits']} / Misses: {stats['misses']}\n"
f"- Hit rate: {stats['hit_rate_pct']}%",
)
return True
if sub == "tokens":
await self._post_token_summary()
return True
if sub == "trace":
await self._post_trace_summary()
return True
if sub == "mode":
# V5.0 FR-10: /poly mode β show current session mode
if self._mode == "yolo":
await self._post(
"coordinator",
f"β‘ **{self._yolo_mode_label()}** β silent pipeline run, Finley posts at end.",
)
else:
await self._post("coordinator", "π **Investigation mode** β full visibility, checkpoints enabled.")
return True
if sub == "help":
await self._post("coordinator", render_help_slack())
return True
return False
async def _post_trace_summary(self) -> None:
"""Post last 10 trace entries to Slack (FR-S3.5 /poly trace)."""
entries = self._trace.read_trace(last_n=10)
if not entries:
await self._post("coordinator", "π **Trace** β no trace entries for this session yet.")
return
lines = [f"π **Trace β last {len(entries)} entries**\n"]
lines.append("| Agent | Latency | Tokens | Cost | Error |")
lines.append("|---|---|---|---|---|")
for e in entries:
role = e.get("agent_role", "?")
ms = e.get("latency_ms", 0)
tokens = e.get("prompt_tokens", 0) + e.get("completion_tokens", 0)
cost = e.get("estimated_cost_usd")
err = e.get("error") or ""
cost_text = f"${cost:.4f}" if cost is not None else "unknown"
lines.append(f"| `{role}` | {ms:,} ms | {tokens:,} | {cost_text} | {err[:40] if err else 'β'} |")
await self._post("coordinator", "\n".join(lines))
async def _post_token_summary(self) -> None:
"""Post session token usage summary (FR-S3.6 β reads from trace.jsonl)."""
trace_entries = self._trace.read_trace()
# Fallback to QuantState.token_log when no trace entries exist yet
if not trace_entries:
state = self.session.research_state
qs = state.quant_state if state else None
if not qs or not qs.token_log:
await self._post("coordinator", "π **Token usage** β no token records for this session yet.")
return
trace_entries = [
{
"agent_role": e.agent_role,
"prompt_tokens": e.prompt_tokens,
"completion_tokens": e.completion_tokens,
"estimated_cost_usd": e.estimated_cost_usd,
"cache_hit": e.cache_hit,
}
for e in qs.token_log
]
by_agent: dict[str, dict] = {}
for entry in trace_entries:
role = entry.get("agent_role", "unknown")
rec = by_agent.setdefault(
role,
{"prompt": 0, "completion": 0, "cost": 0.0, "cached": 0, "unknown_cost": 0},
)
rec["prompt"] += entry.get("prompt_tokens", 0)
rec["completion"] += entry.get("completion_tokens", 0)
cost = entry.get("estimated_cost_usd")
if cost is None:
rec["unknown_cost"] += 1
else:
rec["cost"] += cost
if entry.get("cache_hit"):
rec["cached"] += 1
total_cost = sum(r["cost"] for r in by_agent.values())
lines = [f"π **Token usage β session {self.session.session_id[:8]}**\n"]
lines.append("| Agent | Prompt | Completion | Est. cost | Cache hits |")
lines.append("|---|---|---|---|---|")
for role, rec in sorted(by_agent.items()):
lines.append(
f"| `{role}` | {rec['prompt']:,} | {rec['completion']:,} "
f"| ${rec['cost']:.4f}{' + unknown' if rec['unknown_cost'] else ''} | {rec['cached']} |"
)
unknown_costs = sum(r["unknown_cost"] for r in by_agent.values())
suffix = f" + {unknown_costs} run(s) with unknown cost" if unknown_costs else ""
lines.append(f"\n**Total known estimated cost:** ${total_cost:.4f}{suffix}")
await self._post("coordinator", "\n".join(lines))
"""Coordinator agent β Orchestrator.
The Coordinator is always active. It is the entry point for every message:
it parses @mentions, routes tasks to agents or the human, maintains the
Research State, fires checkpoint gates, and detects @mention loops.
V4.3: Routing now goes through the EventBus. The Coordinator publishes
``AgentCompletedEvent`` / ``AgentBlockedEvent`` / ``HumanInputRequiredEvent``
after each agent run and reacts to them via subscribed handlers. Depth
tracking has moved into ``on_agent_completed``.
This module also exposes the top-level ``CoordinatorService`` which drives an
entire session (CLI or Slack webhook).
"""
from __future__ import annotations
import asyncio
import logging
import re
import time
from dataclasses import dataclass, field
from typing import Any, Callable, Awaitable
from polyhedra.agents.base import Agent, AgentResponse, Mention
from polyhedra.agents.quant.market_scope import V6_MARKETS
from polyhedra.core.agent_router import AgentRouter, QUANT_ROLES as _QUANT_ROLES, ALT_AGENT_MAP as _ALT_AGENT_MAP
from polyhedra.core.cache import SharedCache
from polyhedra.core.cost_gate import CostGate
from polyhedra.core.eventbus import (
EventBus, get_bus, clear_bus,
AgentCompletedEvent, AgentBlockedEvent,
HumanInputRequiredEvent, PortfolioAlertEvent,
)
from polyhedra.core.mention_parser import MentionParser
from polyhedra.core.research_state import ResearchStateManager, Paper, Gap, Decision, Hypothesis
from polyhedra.core.role_registry import RoleRegistry, RoleEntry, HELD_BY_AGENT, HELD_BY_HUMAN
from polyhedra.core.session import Session
from polyhedra.core.state_patcher import StatePatcher
from polyhedra.core.template_builder import TemplateBuilder, render_help_slack
from polyhedra.core.trace_logger import TraceLogger
from polyhedra.core.yolo_context import (
YoloRunContext,
mark_yolo_run_completed,
prepare_yolo_run_context,
)
from polyhedra.services.file_writer import FileWriter
from polyhedra.services.llm_service import LLMService
from polyhedra.services.rag_service import RAGService
logger = logging.getLogger(__name__)
# Re-export for backward compatibility with existing code that imports from here
_MAX_MENTION_DEPTH = 3
_COST_APPROVAL_THRESHOLD = 0.50
# Short labels used in YOLO progress status message (V5.0)
_ROLE_LABELS: dict[str, str] = {
"datafetcher": "DataFetcher",
"trendanalyst": "TrendAnalyst",
"sentimentanalyst": "SentimentAnalyst",
"marketeventwatcher": "MarketEventWatcher",
"optionsflowwatcher": "OptionsFlowWatcher",
"macrocontextwatcher": "MacroContextWatcher",
"unusualeventdetector": "UnusualEventDetector",
"eventrouter": "EventRouter",
"btcanalyst": "BTCAnalyst",
"spyanalyst": "SPYAnalyst",
"qqqanalyst": "QQQAnalyst",
"gldanalyst": "GLDAnalyst",
"quantresearcher": "QuantResearcher",
"backtester": "Backtester",
"riskanalyst": "RiskAnalyst",
"quantstrategist": "QuantStrategist",
"publisher": "Finley",
}
_V5_QUANT_PATH: list[str] = [
"datafetcher",
"trendanalyst",
"sentimentanalyst",
"quantresearcher",
"backtester",
"riskanalyst",
"quantstrategist",
"publisher",
]
_V6_WATCHER_PATH: list[str] = [
"datafetcher",
"trendanalyst",
"marketeventwatcher",
"optionsflowwatcher",
"macrocontextwatcher",
"unusualeventdetector",
"eventrouter",
]
_V6_ASSET_ROLE: dict[str, str] = {
"BTC": "btcanalyst",