PolyHedra / src /polyhedra /agents /coordinator.py
yf176
fix: preserve failed agent token usage in trace
44d82a2
Raw History Blame Contribute Delete
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",