Download docs/IMPLEMENTATION.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 59.3 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/IMPLEMENTATION.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/IMPLEMENTATION.md
-
curl -L -o IMPLEMENTATION.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/IMPLEMENTATION.md
Polyhedra β Full Codebase Implementation Reference
Version: 4.4 | Branch:
V4.4| Python β₯ 3.11
Paper trading simulation only. No real capital. Not financial advice.
Table of Contents
- Project Overview
- Repository Layout
- Package Entry Points
- Core Infrastructure (
core/) - Agent System (
agents/) - Quant Pipeline (
agents/quant/) - Services (
services/) - Messaging (
messaging/) - CLI (
cli/) - Agent Workflow Engine (
agent/) - Schemas (
schemas/) - MCP Server (
server.py) - FastAPI App (
app.py) - Routing System
- Data Flow β Full Quant Chain
- Environment Variables
- Key Design Patterns
- Known Bugs & Fixes Applied
1. Project Overview
Polyhedra is a multi-agent research and paper-trading system that runs as:
| Surface | Entry point | Purpose |
|---|---|---|
| Slack bot | messaging/slack.py |
Live @mention-driven quant chain |
| CLI | cli/main.py β poly command |
Terminal sessions |
| MCP server | server.py β polyhedra command |
VS Code / Cursor tool-call integration |
| FastAPI | app.py |
Slack webhook receiver + health probe |
Two agent families operate in parallel:
- Research family β Scout β Strategist β Critic β Scribe (literature review; disabled from Slack in V4.3)
- Quant family β DataFetcher β TrendAnalyst β SentimentAnalyst β QuantResearcher β Backtester β RiskAnalyst β QuantStrategist β VizAgent + PortfolioMonitor
2. Repository Layout
src/polyhedra/
βββ __init__.py # version = "4.4.0", re-exports main
βββ app.py # FastAPI application factory
βββ server.py # MCP server (polyhedra CLI entry point)
βββ agent/ # Standalone workflow engine (Intent β Workflow β Steps)
β βββ __init__.py
β βββ checkpoint.py
β βββ config.py
β βββ intent_parser.py
β βββ models.py
β βββ research_agent.py
β βββ retry.py
β βββ state.py
β βββ tool_adapter.py
β βββ workflow_generator.py
βββ agents/ # Multi-agent orchestration
β βββ __init__.py
β βββ base.py # Agent ABC, AgentResponse, Mention
β βββ coordinator.py # CoordinatorAgent + CoordinatorService
β βββ critic.py
β βββ scout.py
β βββ scribe.py
β βββ strategist.py
β βββ quant/
β βββ __init__.py
β βββ routing.py # LLM_ROUTING_PROMPT, parse_llm_routing, parse_proposals_block (V4.4)
β βββ datafetcher.py
β βββ trendanalyst.py
β βββ sentimentanalyst.py
β βββ quantresearcher.py
β βββ backtester.py
β βββ riskanalyst.py
β βββ quantstrategist.py
β βββ outputs.py # Typed Pydantic output models (V4.4)
β βββ vizagent.py
β βββ portfoliomonitor.py
βββ cli/
β βββ main.py # Typer app β `poly` command
βββ core/
β βββ __init__.py # Re-exports all core types
β βββ agent_router.py # AgentRouter, QUANT_ROLES, ALT_AGENT_MAP (V4.4)
β βββ cache.py # SharedCache (V4.3)
β βββ cost_gate.py # CostGate β approval threshold logic (V4.4)
β βββ eventbus.py # EventBus + event dataclasses (V4.3)
β βββ mention_parser.py
β βββ research_state.py # ResearchState, QuantState, all domain dataclasses
β βββ role_registry.py
β βββ session.py
β βββ state_patcher.py # StatePatcher β ResearchState update helper (V4.4)
β βββ template_builder.py # TemplateBuilder, COMMAND_REGISTRY, render_help_* (V4.4)
β βββ token_budget.py # TokenBudget, PromptBuilder (V4.3)
β βββ trace_logger.py # TraceLogger β session trace.jsonl writer (V4.4)
βββ messaging/
β βββ __init__.py
β βββ slack.py # SlackIntegration
βββ schemas/
β βββ __init__.py
β βββ paper.py # Pydantic models for Semantic Scholar
βββ services/
βββ __init__.py
βββ alpha_vantage.py
βββ citation_manager.py
βββ context_manager.py
βββ file_writer.py # FileWriter (V4.3: cache + RAG integration)
βββ finnhub.py
βββ literature_review_service.py
βββ llm_service.py
βββ project_initializer.py
βββ rag_service.py
βββ semantic_scholar.py
3. Package Entry Points
Defined in pyproject.toml:
[project.scripts]
polyhedra = "polyhedra.server:main" # MCP server
poly = "polyhedra.cli.main:main" # CLI
Dependencies (core): mcp, httpx, pydantic, bibtexparser, sentence-transformers, numpy, typer, rich, fastapi, uvicorn, slack-bolt, python-dotenv, aiohttp, redis, yfinance, matplotlib
4. Core Infrastructure (core/)
4.1 core/__init__.py
Re-exports all types that other modules need to import from a single location:
SharedCache, AgentBlockedEvent, AgentCompletedEvent, EventBus,
HumanInputRequiredEvent, PortfolioAlertEvent, ResearchState,
ResearchStateManager, TokenUsageEntry, RoleEntry, RoleRegistry,
Session, SessionManager, PromptBuilder, TokenBudget, get_bus
4.2 core/cache.py β SharedCache (V4.3)
In-memory session cache. Replaces file-based shared state; filesystem is persistence backup only.
Cache key conventions:
| Prefix | TTL | Contents |
|---|---|---|
state:<session_id> |
None (never expires) | ResearchState / QuantState |
artifact:<session_id>:<path> |
None | Artifact contents by path |
llm:<prompt_hash> |
None | LLM output by hash |
api:market:<...> |
86 400 s (24 h) | Market API responses |
api:sentiment:<...> |
3 600 s (1 h) | Sentiment API responses |
api:quote:<...> |
60 s (1 min) | Real-time quote responses |
Key classes:
class CacheStats:
hits: int
misses: int
def record_hit() -> None
def record_miss() -> None
def to_dict() -> dict
class SharedCache:
def get(key: str) -> Any | None
def set(key: str, value: Any, ttl: int | None = _SENTINEL) -> None
def invalidate(key: str) -> None
def invalidate_prefix(prefix: str) -> None
def clear() -> None
def flush_to_disk(path: Path) -> None
def warm_from_disk(path: Path) -> None
async def async_flush_to_disk(path: Path) -> None
Module-level helpers:
_SENTINEL = object() # sentinel for "use default TTL"
prompt_hash(prompt: str) -> str # SHA-256 hex[:16] of prompt
Bug fixed:
_SENTINELmust be at module level β walrus operator:=is illegal in default parameter positions.
4.3 core/eventbus.py β EventBus (V4.3)
In-process pub/sub. Agents emit events; Coordinator reacts as subscriber. No external broker.
Event dataclasses:
@dataclass
class AgentCompletedEvent:
session_id: str
agent_role: str
artifact_path: str | None
next_role: str | None # None = chain complete
reason: str
depth: int
content: str
updates_state: bool
state_patch: dict[str, Any]
checkpoint_required: bool
checkpoint_summary: str
origin_id: str # chain origin message_id for depth tracking
@dataclass
class AgentBlockedEvent:
session_id: str
agent_role: str
reason: str
missing_artifact: str | None
suggested_role: str | None
content: str
@dataclass
class HumanInputRequiredEvent:
session_id: str
agent_role: str
question: str
suggested_templates: str
content: str
@dataclass
class PortfolioAlertEvent:
session_id: str
position_id: str
ticker: str
alert_type: str # "take_profit" | "stop_loss" | "move_pct"
current_price: float
threshold: float
content: str
EventBus API:
class EventBus:
def subscribe(event_type: type, handler: Callable) -> None
def unsubscribe(event_type: type, handler: Callable) -> None
async def publish(event: Any) -> None
async def _call_handler(handler: Callable, event: Any) -> None
# Module-level per-session bus registry
def get_bus(session_id: str) -> EventBus
def clear_bus(session_id: str) -> None
4.4 core/research_state.py β Domain Model
All domain dataclasses for research and quant state.
Research domain:
@dataclass class Gap: description, source_papers, confidence
@dataclass class Hypothesis: statement, methodology_sketch, confidence, created_at
@dataclass class Paper: title, paper_id, year, relevance_score, one_line_summary, bibtex_key
@dataclass class Decision: description, rationale, made_by, timestamp
Quant domain:
@dataclass class Signal: signal_id, name, ticker, entry_condition, exit_condition, confidence, assumptions, created_at
@dataclass class BacktestResult: signal_id, ticker, win_rate, avg_return_pct, max_drawdown_pct, sharpe_ratio, num_trades, notes, created_at
@dataclass class TradeProposal: proposal_id, ticker, direction, entry_condition, target_entry_price, take_profit, stop_loss, position_size_pct, rationale, confidence, risk_rating, status, created_at
@dataclass class PaperPosition: position_id, ticker, direction, entry_price, size_pct, opened_at, proposal_id, status, take_profit, stop_loss, close_price, close_date
@dataclass class TradeEvent: event_id, proposal_id, action, reason, timestamp
@dataclass class TokenUsageEntry: agent_role, timestamp, prompt_tokens, completion_tokens, estimated_cost_usd, cache_hit
Top-level state:
@dataclass class QuantState:
watchlist: list[str]
last_fetch: str | None
last_run: str | None
signals: list[Signal]
backtest_results: list[BacktestResult]
risk_ratings: dict[str, str]
trade_proposals: list[TradeProposal]
portfolio: list[PaperPosition]
trade_log: list[TradeEvent]
alerts: list[str]
monitor_paused: bool
last_monitor_run: str | None
token_log: list[TokenUsageEntry]
def to_dict() / from_dict() / to_markdown()
@dataclass class ResearchState:
goal: str
field: str
gaps: list[Gap]
active_hypothesis: Hypothesis | None
key_papers: list[Paper]
decisions: list[Decision]
open_questions: list[str]
pending_tasks: list[str]
last_updated: str
version: int
quant_state: QuantState | None
def to_dict() / from_dict() / to_markdown() / compress()
Constants:
_CHARS_PER_TOKEN = 4
_MAX_TOKENS = 4_000
_MAX_CHARS = 16_000
4.5 core/session.py β Session Management
_SESSIONS_DIR = Path.home() / ".polyhedra" / "sessions"
@dataclass class ThreadMessage:
from_role: str
content: str
message_id: str
timestamp: str
metadata: dict
def to_dict() / from_dict()
class Session:
session_id: str
session_dir: Path
state_manager: ResearchStateManager
registry: RoleRegistry
goal: str
active_roles: list[str]
created_at: str
platform: str
def post(role, content, message_id, metadata) -> ThreadMessage
def thread_history(limit) -> list[ThreadMessage]
def full_thread() -> list[dict]
@property research_state -> ResearchState
def save_meta() / load_meta()
class SessionManager:
def create(goal, platform, roles) -> Session
def resume(session_id) -> Session
def list_sessions() -> list[dict]
def export(session_id) -> Path
# V4.4 additions (FIX-2)
def active_sessions_with_positions() -> list[str] # sessions that have open positions
def _registry_path() -> Path # ~/.polyhedra/sessions/registry.json
def _save_registry(entry: dict) -> None # persists session β positions map
4.6 core/token_budget.py β Token Budget & Prompt Assembly (V4.3)
Agents declare a TokenBudget. PromptBuilder enforces it: never trims system, task, or routing; trims context first, then thread.
@dataclass class TokenBudget:
system: int = 500 # role + constraints β NEVER trimmed
context: int = 2000 # RAG artifact chunks β trimmed first
task: int = 500 # task instruction β NEVER trimmed
thread: int = 500 # recent messages β trimmed last
routing: int = 200 # routing block β NEVER trimmed
total: int = 4000 # hard ceiling
@property fixed -> int # system + task + routing
DEFAULT_BUDGET = TokenBudget() # applied when agent declares none
@dataclass class Chunk:
text: str
score: float
metadata: dict
def token_count() -> int
class PromptBuilder:
def set_system(text: str) -> PromptBuilder
def set_task(text: str) -> PromptBuilder
def set_routing(text: str) -> PromptBuilder
def set_context(chunks: list[Chunk]) -> PromptBuilder
def set_thread(messages: list[dict]) -> PromptBuilder
def build() -> str
def _trim_thread(budget: int) -> str
def _assemble() -> str
class PromptOverBudgetError(Exception): ...
4.7 core/role_registry.py
HELD_BY_AGENT = "agent"
HELD_BY_HUMAN = "human"
@dataclass class RoleEntry:
role: str
agent: Agent
held_by: str
takeover_message_id: str | None
@property is_human -> bool
@property is_agent -> bool
class RoleRegistry:
def register(role, agent) -> None
def unregister(role) -> None
def get(role) -> RoleEntry | None
def roles() -> list[str]
def agent_roles() / human_roles() -> list[str]
def take_over(role, message_id) -> None
def reinstate(role) -> None
def to_dict() -> dict
def summary() -> str
4.8 core/mention_parser.py
_AT_MENTION_RE = re.compile(r"@(\w+)")
@dataclass class ParsedMention:
mentioned_roles: list[str]
human_addressed: bool
raw_text: str
class MentionParser:
def parse(text: str) -> ParsedMention
def extract_roles(text: str) -> list[str]
def strip_mentions(text: str) -> str
4.9 core/agent_router.py β AgentRouter (V4.4)
Extracted from coordinator.py (STRUCT-1). Owns all routing constants and depth tracking.
QUANT_ROLES: frozenset[str] = frozenset({
"datafetcher", "trendanalyst", "sentimentanalyst",
"quantresearcher", "backtester", "riskanalyst",
"quantstrategist", "vizagent", "portfoliomonitor", "human"
})
ALT_AGENT_MAP: dict[str, str] = { # skip-forward map on agent block
"trendanalyst": "sentimentanalyst",
"sentimentanalyst": "quantresearcher",
"quantresearcher": "backtester",
"backtester": "riskanalyst",
"riskanalyst": "quantstrategist",
"quantstrategist": "human",
}
class AgentRouter:
def init_origin(message_id: str) -> None # set chain origin for depth tracking
def can_dispatch(role: str) -> bool # depth gate check
def record_dispatch(role: str) -> None # increment depth counter
def reset_depth() -> None # reset after chain completes
def current_depth() -> int
def next_alt(role: str) -> str | None # skip-forward lookup
def is_quant_role(role: str) -> bool
4.10 core/template_builder.py β TemplateBuilder (V4.4)
Extracted from coordinator.py (STRUCT-1 / STRUCT-4). Owns COMMAND_REGISTRY and help renderers.
@dataclass class CommandEntry:
command: str # e.g. "/poly approve"
description: str
example: str | None
COMMAND_REGISTRY: list[CommandEntry] # 25 entries covering all /poly and @agent commands
def render_help_slack() -> str # Block Kitβformatted Slack help message
def render_help_cli() -> str # Rich table for terminal
class TemplateBuilder:
def build(touchpoint: str, *, next_role: str, proposal_id: str,
session_id: str) -> str
# Touchpoints: "checkpoint" | "trade_proposals" | "agent_blocked"
# | "uncertainty" | "resume"
def _opts_checkpoint() -> list[str]
def _opts_trade_proposals(proposal_id: str) -> list[str]
def _opts_agent_blocked(next_role: str) -> list[str]
def _opts_uncertainty() -> list[str]
def _opts_resume(session_id: str) -> list[str]
4.11 core/state_patcher.py β StatePatcher (V4.4)
Extracted from coordinator.py (STRUCT-1). Applies AgentResponse.state_patch to persisted ResearchState.
class StatePatcher:
def validate(patch: dict) -> list[str] # returns list of validation errors
def apply(session: Session, patch: dict) -> None
# Loads ResearchState, applies patch keys, compresses, saves back to disk
4.12 core/cost_gate.py β CostGate (V4.4)
Extracted from coordinator.py (STRUCT-1). Encapsulates cost approval threshold logic.
_COST_APPROVAL_THRESHOLD = 0.50 # USD
class CostGate:
def requires_approval(estimated_cost: float) -> bool
def format_approval_request(estimated_cost: float, action: str) -> str
4.13 core/trace_logger.py β TraceLogger (V4.4)
New. Writes per-run JSON entries to {session_dir}/trace.jsonl. Injected into each agent by Coordinator (STRUCT-3).
class TraceLogger:
def __init__(session_dir: Path)
def start_run(agent_role: str, prompt_tokens: int) -> str # returns run_id sha256_prefix
def end_run(run_id: str, completion_tokens: int,
next_role: str | None, cost: float) -> None
def read_trace(last_n: int = 10) -> list[dict] # for /poly trace
def _sha256_prefix(data: str) -> str # module-level 8-char ID helper
5. Agent System (agents/)
5.1 agents/base.py β Agent ABC
@dataclass class Mention:
mentioned_role: str
from_role: str
content: str
thread_message_id: str | None
timestamp: str
metadata: dict[str, Any]
@dataclass class AgentResponse:
agent_role: str
content: str
mentions: list[str] # roles to dispatch next
artifact_path: str | None
artifact_mode: str # "overwrite" | "append"
updates_state: bool
state_patch: dict[str, Any]
checkpoint_required: bool
checkpoint_summary: str
error: str | None
output: BaseModel | None = None # typed output model (V4.4 STRUCT-2)
metadata: dict[str, Any] # deprecated in favour of output (V4.4)
class Agent(ABC):
name: str # display name
role: str # kebab-case routing key
role_title: str
system_prompt: str
files: FileWriter # injected by coordinator
bus: EventBus | None # injected by coordinator
token_budget: TokenBudget # class-level default
trace: "TraceLogger | None" = None # injected by coordinator (V4.4 STRUCT-3)
logger: logging.Logger
@abstractmethod async def handle(mention, thread_context, research_state) -> AgentResponse
@abstractmethod async def can_handle(mention) -> bool
def _format_thread_context(thread_context) -> str
def _format_research_state(research_state) -> str
def _log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit) -> None
5.2 agents/coordinator.py β Coordinator
Constants (V4.4 β moved to delegated helpers):
_MAX_MENTION_DEPTH = 3 # hard stop for non-quant chains
# _QUANT_ROLES and _ALT_AGENT_MAP have moved to core/agent_router.py (V4.4 STRUCT-1)
V4.4 delegates (injected at __init__):
self._routerβAgentRouter(depth tracking, quant role set, skip-forward map)self._templatesβTemplateBuilder(input suggestion templates)self._patcherβStatePatcher(ResearchState patch application)self._cost_gateβCostGate(approval threshold check)self._traceβTraceLogger(sessiontrace.jsonlwriter; injected into each agent)
CoordinatorService drives session lifecycle. On each inbound message:
- Parses @mentions via
MentionParser - Assembles
Mentionwithfrom_role,thread_message_id - Calls
self._router.can_dispatch()+record_dispatch()+init_origin() - Finds matching agent via
RoleRegistry; injectsentry.agent.trace = self._trace - Calls
agent.handle()inside an event-bus transaction - Publishes
AgentCompletedEvent/AgentBlockedEvent/HumanInputRequiredEvent - Depth-tracks via
AgentRouter; pauses (not hard-stops) at limit for quant chain - Applies
state_patchviaself._patcher.apply() - Cost gate via
self._cost_gate.requires_approval()+format_approval_request()
_build_input_templates() β now delegates to self._templates.build(); see core/template_builder.py.
_handle_slash_command():
/poly traceβ_post_trace_summary()β posts last 10 trace entries as Slack table/poly helpβrender_help_slack()fromTemplateBuilder
_post_token_summary() β reads from trace.jsonl first; falls back to QuantState.token_log.
5.3 Research Agents (agents/scout.py, strategist.py, critic.py, scribe.py)
Status in V4.3: Implemented but disabled from Slack session registration. Only 9 quant agents are registered.
| Agent | Role | Job |
|---|---|---|
ScoutAgent |
scout |
Semantic Scholar search; _MAX_PAPERS = 50, default _DEFAULT_LIMIT = 20 |
StrategistAgent |
strategist |
Plans next research steps from Scout summary; uses LLM |
CriticAgent |
critic |
Reviews draft sections for logical gaps; uses LLM |
ScribeAgent |
scribe |
Writes/appends paper sections; uses LLM; _KNOWN_SECTIONS set |
All four use lazy LLM initialisation:
@property
def _llm(self) -> LLMService:
if self.__llm is None:
self.__llm = self._llm_service or LLMService()
return self.__llm
6. Quant Pipeline (agents/quant/)
6.1 Pipeline Overview
Human (@datafetcher)
β
βΌ
DataFetcherAgent ββββ Finnhub API βββββΊ quant/raw/<TICKER>_<date>.json
β quant/raw/<TICKER>_<date>_summary.md
β (trend_analysis_<date>.md absent β trendanalyst)
β (trend_analysis_<date>.md present β sentimentanalyst) β V4.3 mid-chain fix
βΌ
TrendAnalystAgent (LLM) βββββββββββββββββββββββΊ quant/trend_analysis_<date>.md
β (cycle guard: datafetcher β sentimentanalyst)
βΌ
SentimentAnalystAgent (LLM) ββββββββββββββββββββΊ quant/sentiment_analysis_<date>.md
βΌ
QuantResearcherAgent (LLM) βββββββββββββββββββββΊ quant/signal_hypotheses_<date>.md
βΌ
BacktesterAgent (LLM) ββββββββββββββββββββββΊ quant/backtest_results_<date>.md
βΌ
RiskAnalystAgent (LLM) ββββββββββββββββββββββΊ quant/risk_assessment_<date>.md
βΌ
QuantStrategistAgent (LLM) βββββββββββββββββββββΊ quant/trade_proposals_<date>.md
β (always β @human)
βΌ
Human (reviews + approves)
β
βΌ
VizAgent (on demand) ββββββββββββββββββββββΊ quant/viz/<chart_type>_<TICKER>_<date>.png
PortfolioMonitorAgent (scheduled) ββββββββββββββΊ quant/portfolio_log_<date>.md
6.2 agents/quant/routing.py β LLM Routing
QUANT_ROLES: frozenset[str] = frozenset({
"datafetcher", "trendanalyst", "sentimentanalyst",
"quantresearcher", "backtester", "riskanalyst",
"quantstrategist", "vizagent", "portfoliomonitor", "human"
})
LLM_ROUTING_PROMPT: str # Appended to every LLM agent prompt (see Β§14)
def parse_llm_routing(content: str | None) -> tuple[str | None, str, str]:
"""
Extracts last {"next": "<role>", "reason": "<...>"} JSON block.
Returns (next_role, reason, stripped_content).
next_role is None if JSON is absent or next=null.
Validates next_role against QUANT_ROLES.
"""
# V4.4 additions (FIX-3) β structured trade proposal parsing
def parse_proposals_block(content: str) -> list[dict]:
"""
Extracts ```proposals ... ``` JSON array block from QuantStrategist output.
Each element is validated with _validate_proposal().
Returns empty list if block is absent or malformed.
"""
def _balance_brackets(text: str) -> str # repair truncated JSON before parse attempt
def _validate_proposal(obj: dict) -> bool # checks required keys + value ranges
6.3 DataFetcherAgent (datafetcher.py)
- No LLM β routing is fully deterministic
- Resolves watchlist from:
research_state.quant_state.watchlistβ @mention text extraction βPOLYHEDRA_QUANT_WATCHLISTenv - Calls
FinnhubService.fetch_ticker_data()per ticker - Writes
quant/raw/<TICKER>_<date>.jsonandquant/raw/<TICKER>_<date>_summary.md - Routing logic (V4.4):
# _fetch_one() returns 4-tuple: (fetched: bool, cap_hit: bool, ticker: str, has_ohlcv: bool)
# _fetch_all() returns 5-tuple; tracks ohlcv_failures, sets all_ohlcv_failed
if all_ohlcv_failed:
# FIX-5: route to @human with yfinance_alert: True in state_patch
next_mentions = ["human"]
elif not fetched and cap_hit:
next_mentions = ["human"]
elif trend_exists:
next_mentions = ["sentimentanalyst"] # mid-chain β skip TrendAnalyst
else:
next_mentions = ["trendanalyst"] # fresh session start
_is_valid_ticker(token: str) -> bool(V4.4 FIX-8) β replaces_SKIP_TOKENS; checks againstPOLYHEDRA_VALID_TICKERSenv var allow-list if set, otherwise falls back to regex heuristics
6.4 TrendAnalystAgent (trendanalyst.py)
- TokenBudget:
system=500, context=2000, task=500, thread=500, routing=200, total=4000 - Reads
quant/raw/*_<date>_summary.mdfiles written by DataFetcher - If no summaries exist β returns
AgentResponse(mentions=["datafetcher"]) - LLM call β
parse_llm_routing - Cycle guard (V4.3): forcibly overrides any
datafetcherrouting tosentimentanalyst
if next_role == "datafetcher":
logger.warning("TrendAnalyst: suppressing datafetcher re-route (cycle guard) β sentimentanalyst")
next_role = "sentimentanalyst"
_ETF_CONSTRAINTβ instructs LLM to omit earnings section for ETFs- Writes
quant/trend_analysis_<date>.md
Prompt structure:
[1] ROLEβ system prompt[2] INPUTSβ tickers + raw summaries (capped 4000 chars) + thread context[3] TASKβ per-ticker sections: price trend, volume, momentum, earnings[4] CONSTRAINTSβ ETF rule, data gap rule, datafetcher cycle guard rule[5] ROUTINGβLLM_ROUTING_PROMPT
6.5 SentimentAnalystAgent (sentimentanalyst.py)
- TokenBudget: same as TrendAnalyst
- Reads trend analysis + raw summaries
- Three additional constraints:
_ETF_CONSTRAINTβ skip earnings for ETFs_THIN_SENTIMENT_CONSTRAINTβ >50% zero-score news β flag as insufficient, routedatafetcher_NO_REPACKAGE_CONSTRAINTβ must add new signal layer beyond technical findings
- Writes
quant/sentiment_analysis_<date>.md
6.6 QuantResearcherAgent (quantresearcher.py)
- TokenBudget: same as TrendAnalyst
- Reads trend + sentiment analyses
- Identifies named signal hypotheses with entry/exit conditions, confidence level, and falsification criteria
- Does NOT backtest
- Writes
quant/signal_hypotheses_<date>.md
6.7 BacktesterAgent (backtester.py)
- TokenBudget: same as TrendAnalyst
_MIN_TRADES_THRESHOLD = 5β signals with fewer occurrences are flagged as statistically weak- Reads signal hypotheses + raw OHLCV summaries
- Reports honest metrics: win rate, avg return %, max drawdown %, Sharpe ratio, trade count
- Never cherry-picks results
- Writes
quant/backtest_results_<date>.md
6.8 RiskAnalystAgent (riskanalyst.py)
- TokenBudget: same as TrendAnalyst
- Reads backtest results + signal hypotheses + portfolio state
- Evaluates: correlation risk, concentration risk, drawdown risk, stress scenarios
- Assigns risk verdict per signal: Acceptable / Elevated / Reject
- Does NOT make allocation decisions
- Writes
quant/risk_assessment_<date>.md
6.9 QuantStrategistAgent (quantstrategist.py)
- TokenBudget: same as TrendAnalyst
_MAX_PROPOSALS = 3β hard cap on proposals per run- Hard constraints:
- Only proposes Acceptable or Elevated signals (never Reject)
- Elevated signals must include specific risk mitigation note
- Always routes to
@humanβ never chains further
- Writes
quant/trade_proposals_<date>.md - V4.4 FIX-3: prompt now requires a fenced
```proposals ```JSON block;parse_proposals_block()fromrouting.pyextracts and validates it; narrative text before the block is preserved separately.
6.10 VizAgent (vizagent.py)
- TokenBudget: same as TrendAnalyst
- Triggered by TrendAnalyst, Backtester, RiskAnalyst, or direct human @mention
_CHART_KEYWORDSβ maps free-text keywords to chart type:"candlestick"/"candle"β"candlestick""rsi"/"macd"β"rsi_macd""backtest"β"backtest""risk"/"heatmap"β"risk_heatmap""portfolio"/"pnl"/"p&l"β"portfolio_pnl"
- Saves charts to
quant/viz/<chart_type>_<ticker>_<date>.png - Uses
matplotlibfor static PNG generation - LLM generates a 2β3 sentence chart caption
6.11 PortfolioMonitorAgent (portfoliomonitor.py)
- Schedule: every
POLYHEDRA_MONITOR_INTERVALminutes (default 30), MonβFri 09:30β16:00 ET _DEFAULT_ALERT_MOVE_PCT = 2.0β threshold for unrealised move alerts- On each run:
- Fetches latest quote for every open position via
FinnhubService.get_quote() - Evaluates take-profit, stop-loss, Β±move thresholds
- Publishes
PortfolioAlertEventon breach - Writes
quant/portfolio_log_<date>.md
- Fetches latest quote for every open position via
_is_market_hours(tz_name)β checks MonβFri 09:30β16:00 in given timezone; graceful fallback ifzoneinfounavailable
Environment variables specific to PortfolioMonitor:
POLYHEDRA_MONITOR_INTERVAL interval in minutes (default: 30)
POLYHEDRA_MARKET_TZ timezone string (default: America/New_York)
POLYHEDRA_ALERT_MOVE_PCT move threshold percentage (default: 2.0)
6.12 agents/quant/outputs.py β Typed Output Models (V4.4)
Seven Pydantic BaseModel subclasses matching each quant agent's structured output. Assigned to AgentResponse.output (STRUCT-2).
class DataFetcherOutput(BaseModel):
tickers: list[str]
fetched: list[str]
failed: list[str]
all_ohlcv_failed: bool
class TrendAnalystOutput(BaseModel):
tickers: list[str]
artifact_path: str
class SentimentAnalystOutput(BaseModel):
tickers: list[str]
artifact_path: str
class QuantResearcherOutput(BaseModel):
signal_count: int
artifact_path: str
class BacktesterOutput(BaseModel):
tested_signals: list[str]
artifact_path: str
class RiskAnalystOutput(BaseModel):
verdicts: dict[str, str] # signal_id β "Acceptable" | "Elevated" | "Reject"
artifact_path: str
class QuantStrategistOutput(BaseModel):
proposals: list[dict] # validated proposal dicts from parse_proposals_block()
artifact_path: str
7. Services (services/)
7.1 services/llm_service.py β LLM Abstraction
Exceptions:
ConfigurationError # missing API key or config
RateLimitError # HTTP 429; carries retry_after: int | None
AuthenticationError # 401/403
TimeoutError # request timeout
Abstract adapter:
class LLMAdapter(ABC):
async def complete(prompt, model=None) -> tuple[str, int, int]
# Returns (response_text, input_tokens, output_tokens)
def calculate_cost(input_tokens, output_tokens, model) -> float
async def close() -> None
AnthropicAdapter:
DEFAULT_MODEL = "claude-3-5-sonnet-20241022"
PRICING = {
"claude-3-5-sonnet-20241022": {"input": 3.0, "output": 15.0},
# ... per million tokens
}
GeminiAdapter: Same structure with Gemini pricing table.
LLMService wraps the active adapter selected from environment:
class LLMService:
async def complete(prompt: str) -> tuple[str, int, int]
def estimate_tokens(text: str) -> int # len(text) // 4
def calculate_cost(input_tokens, output_tokens) -> float
7.2 services/file_writer.py β FileWriter (V4.3)
Single shared file I/O service. All agents use this exclusively β no agent calls open() directly.
class FileWriter:
def __init__(session_dir, session_id="", cache=None, rag=None)
def read(path: str) -> str | None
# 1. Check SharedCache (artifact:<session_id>:<path>)
# 2. On miss: read disk, populate cache
def write(path: str, content: str, mode: str = "overwrite") -> None
# 1. Write to disk (creates parent dirs)
# 2. Update SharedCache
# 3. Call rag.index_artifact()
# 4. If writing agent is "datafetcher": invalidate artifact:* keys for ticker
def list(prefix: str = "") -> list[str]
# Returns relative paths under session_dir matching prefix
def exists(path: str) -> bool
_extract_ticker_from_path(path) β module-level helper: extracts ticker symbol from artifact paths like quant/raw/AAPL_2026-03-26.json.
7.3 services/finnhub.py β Finnhub Market Data
Rate-aware client. Free tier: 60 calls/minute.
_BASE_URL = "https://finnhub.io/api/v1"
_PER_MINUTE_LIMIT = 60
_MIN_CALL_DELAY = 1.1 # seconds between calls
_CANDLE_DAYS = 90
class RateLimitExceeded(Exception): ...
class FinnhubService:
async def get_quote(ticker: str) -> dict
# Returns: c (price), h (high), l (low), o (open), pc (prev close), t (timestamp)
async def fetch_ticker_data(ticker: str, session_dir: Path) -> dict
# Fetches:
# - OHLCV daily candles (90 days) β TIME_SERIES_DAILY_ADJUSTED
# - SMA-20, EMA-20, RSI-14, MACD(12/26/9) computed locally
# - Company news (last 30 days) β NEWS_SENTIMENT
# - Earnings (last 8 quarters) β EARNINGS
# Outputs AV-compatible JSON
def calls_remaining_today() -> int
async def _call(endpoint: str, params: dict) -> dict
def _fetch_ohlcv_yfinance(ticker: str) -> dict | None # V4.4 FIX-5: returns None on any exception
def _compute_sma(prices, period) -> list[float]
def _compute_ema(prices, period) -> list[float]
def _compute_rsi(prices, period=14) -> list[float]
def _compute_macd(prices, fast=12, slow=26, signal=9) -> dict
def _news_to_av(news: list) -> dict # normalise to AV news format
def _earnings_to_av(earnings: list) -> dict # normalise to AV earnings format
V4.4 FIX-5:
_fetch_ohlcv_yfinanceis now wrapped intry/except, returningNoneon any exception.fetch_ticker_data()checks forNoneand setshas_ohlcv=Falsein the returned tuple; DataFetcher usesall_ohlcv_failedto route to@humanwithyfinance_alert: True.
7.4 services/alpha_vantage.py
_BASE_URL = "https://www.alphavantage.co/query"
_DAILY_LIMIT = 25
_PER_MINUTE_LIMIT = 5
_BATCH_DELAY = 15.0 # seconds between batches
class DailyCapExceeded(Exception): ...
class AlphaVantageService:
async def fetch_ticker_data(ticker, session_dir) -> dict
def calls_remaining_today() -> int
async def _call(params: dict) -> dict
def _reset_daily_if_needed() -> None
7.5 services/rag_service.py β RAG (V4.4)
class RAGService:
def __init__(project_root, model_name="all-MiniLM-L6-v2",
session_id: str = "") # V4.4 FIX-1: session-scoped init
# Embeddings stored at ~/.polyhedra/sessions/{session_id}/embeddings.json
# (previously: shared literature/embeddings.json β caused cross-session leakage)
def _load_model() -> SentenceTransformer
def _load_index() -> dict # deserialises JSON; returns {} if file absent
def is_indexed() -> bool
def index_papers(papers: list[dict]) -> None
def query(query_text: str, top_k=5) -> list[dict]
def index_artifact(path: str, content: str, session_id: str) -> None
def query_artifacts(query_text: str, session_id: str, top_k=5) -> list[Chunk]
def rebuild_artifact_index_from_disk(session_dir: Path, session_id: str) -> None
7.6 services/semantic_scholar.py
BASE_URL = "https://api.semanticscholar.org/graph/v1"
MAX_RETRIES = 3
RETRY_DELAY = 1.0 # seconds
class SemanticScholarService:
async def search(query, limit=20, fields=None) -> SemanticScholarResponse
async def get_paper(paper_id: str) -> Paper
async def generate_bibtex(paper: Paper) -> str
async def query_similar_papers(query_text: str, limit=10) -> list[Paper]
async def close() -> None
7.7 services/citation_manager.py
class CitationManager:
bib_path: Path
def load() -> dict[str, str] # key β bibtex entry
def save(entries: dict) -> None
def add_entry(key: str, bibtex: str) -> None
def get_all_keys() -> list[str]
def get_all_entries() -> dict[str, str]
7.8 services/literature_review_service.py
DEPTH_CONFIG = {
"quick": {"min": 400, "max": 800, "target": 600},
"standard": {"min": 800, "max": 1600, "target": 1200},
"deep": {"min": 1600, "max": 3200, "target": 2400},
}
class LiteratureReviewService:
def generate(papers: list[Paper], depth: str = "standard") -> str
def estimate_cost(papers: list[Paper], depth: str) -> float
def _prepare_papers_summary(papers) -> str
def _format_authors(authors) -> str
def _build_prompt(papers_summary, depth) -> str
def _extract_metadata(content: str) -> dict
8. Messaging (messaging/)
8.1 messaging/slack.py β SlackIntegration
_ROLE_DISPLAY β maps role keys to Slack display names with emoji:
{
"datafetcher": "DataFetcher π",
"trendanalyst": "TrendAnalyst π",
"sentimentanalyst": "SentimentAnalyst π°",
"quantresearcher": "QuantResearcher π¬",
"backtester": "Backtester β±οΈ",
"riskanalyst": "RiskAnalyst β οΈ",
"quantstrategist": "QuantStrategist π―",
"vizagent": "VizAgent π",
"portfoliomonitor": "PortfolioMonitor π",
# ... research agents
}
SlackIntegration:
class SlackIntegration:
def __init__(signing_secret: str, bot_token: str)
def mount_to_fastapi(app: FastAPI) -> None
def _build_slack_app() -> AsyncApp
async def _process_mention(body, say, client) -> None
async def _init_from_mention(body, say, client) -> None
# Slash commands:
async def _cmd_init(body, ...) -> None
async def _cmd_status(body, ...) -> None
async def _cmd_approve(body, ...) -> None
async def _cmd_reject(body, ...) -> None
async def _cmd_role(body, ...) -> None
async def _cmd_export(body, ...) -> None
Session registration (V4.3, quant-only):
Both _init_from_mention and _cmd_init register exactly these 9 quant agents:
selected_roles = [
"datafetcher", "trendanalyst", "sentimentanalyst",
"quantresearcher", "backtester", "riskanalyst",
"quantstrategist", "vizagent", "portfoliomonitor"
]
Research agents (Scout, Strategist, Critic, Scribe) are not registered.
_find_proposal_in_md(content: str, proposal_id: str) -> dict (V4.4 FIX-3) β replaces _parse_proposal_block; uses parse_proposals_block() from routing.py to extract validated proposal by proposal_id.
_monitor_loop() (V4.4 FIX-2) β uses active_sessions_with_positions() to filter only sessions with open positions before iterating; avoids unnecessary API calls for idle sessions.
Bug fixed:
_SayClient.chat_postMessagehad duplicatechannelkwarg β renamed positional param from_channeltochannel.
9. CLI (cli/)
9.1 cli/main.py
Typer app β poly command family:
poly init [--goal TEXT] [--field TEXT] # Start new research session
poly search QUERY [--limit INT] # Invoke ScoutAgent directly
poly state [--session-id TEXT] # Print ResearchState as markdown
poly resume [--session-id TEXT] # Re-attach to existing session
poly export [--session-id TEXT] # Export artifacts to zip
poly role take <role> # Human takes over a role
poly role release <role> # Reinstate agent for role
poly mcp [--host TEXT] [--port INT] # Start MCP server
poly sessions # List all saved sessions
poly cache stats # SharedCache hit/miss stats (V4.3)
poly tokens [--session-id TEXT] # Token usage log table (V4.3)
poly trace [--session-id TEXT] [--last N] # Print last N trace entries (V4.4 STRUCT-3)
poly help # Rich table of all commands (V4.4 STRUCT-4)
Internal helpers:
_build_full_session(goal, field) -> Session
_latest_session_id() -> str | None
10. Agent Workflow Engine (agent/)
Standalone workflow runner β distinct from the multi-agent system. Used by the MCP server for structured tool-call sequences.
10.1 agent/models.py
class StepStatus(Enum):
pending | running | completed | failed | skipped
class IntentType(Enum):
research_survey | paper_comparison | gap_analysis | citation_finding | unknown
@dataclass class Intent:
type: IntentType
topic: str
parameters: dict
confidence: float
raw_command: str
@dataclass class WorkflowStep:
name: str
tool: str
arguments: dict
critical: bool
timeout: int
retry_count: int
description: str
@dataclass class Workflow:
name: str
description: str
steps: list[WorkflowStep]
metadata: dict
def validate() -> bool
@dataclass class WorkflowResult:
success: bool
results: dict
errors: list[str]
message: str
elapsed_seconds: float
10.2 agent/research_agent.py
class ResearchAgent:
def __init__(tool_adapter, intent_parser, workflow_generator, config)
async def execute_command(command: str) -> WorkflowResult
async def execute_workflow(workflow: Workflow) -> WorkflowResult
async def _execute_step(step: WorkflowStep, context: dict) -> dict
def _resolve_arguments(args: dict, context: dict) -> dict
10.3 agent/retry.py
@dataclass class RetryConfig:
max_attempts: int = 3
initial_delay: float = 1.0
max_delay: float = 60.0
exponential_base: float = 2.0
jitter: bool = True
class CircuitBreaker:
failure_threshold: int
timeout: float
def record_success() / record_failure() / can_attempt() / reset()
async def retry_with_backoff(fn, config: RetryConfig, circuit_breaker=None) -> Any
10.4 agent/checkpoint.py
@dataclass class CheckpointConfig:
cost_threshold: float = 0.50
require_approval: bool = True
auto_approve_below: float = 0.10
timeout: int = 300 # seconds
@dataclass class Checkpoint:
step_name: str
operation: str
estimated_cost: float
rationale: str
auto_approved: bool
user_approved: bool
class CheckpointManager:
def should_checkpoint(estimated_cost: float) -> bool
def request_approval(checkpoint: Checkpoint) -> bool
def get_checkpoint_history() -> list[Checkpoint]
def clear_history() -> None
10.5 agent/state.py
class StateManager:
state_dir: Path
def save_state(state: WorkflowState) -> None
def load_state(workflow_id: str) -> WorkflowState | None
def delete_state(workflow_id: str) -> None
def list_workflows() -> list[str]
def cleanup_old_states(days: int = 7) -> int
def can_resume(workflow_id: str) -> bool
10.6 agent/config.py
@dataclass class AgentConfig:
max_retry_attempts: int = 3
initial_retry_delay: float = 1.0
max_retry_delay: float = 60.0
exponential_base: float = 2.0
retry_jitter: bool = True
circuit_breaker_threshold: int = 5
circuit_breaker_timeout: float = 60.0
checkpoint_cost_threshold: float = 0.50
checkpoint_auto_approve_below: float = 0.10
checkpoint_timeout: int = 300
checkpoint_enabled: bool = True
state_dir: Path = Path("~/.polyhedra/state")
state_cleanup_days: int = 7
log_level: str = "INFO"
@classmethod def from_env() -> AgentConfig
@classmethod def from_file(path: Path) -> AgentConfig
def to_dict() -> dict
def save(path: Path) -> None
11. Schemas (schemas/)
Pydantic models for Semantic Scholar API responses:
class Author(BaseModel):
name: str
author_id: str | None
class Paper(BaseModel):
id: str
title: str
authors: list[Author]
year: int | None
venue: str | None
abstract: str | None
citation_count: int
bibtex_key: str | None
bibtex_entry: str | None
url: str | None
pdf_url: str | None
fields_of_study: list[str]
class SemanticScholarResponse(BaseModel):
total: int
offset: int
next_offset: int | None
data: list[Paper]
12. MCP Server (server.py)
Entry point: polyhedra command. Exposes research tools to VS Code / Cursor via the Model Context Protocol.
DEFAULT_PAPERS_PATH = "literature/papers.json"
def get_project_root() -> Path # returns Path.cwd()
def _generate_bibtex(paper) -> str # constructs BibTeX entry from paper metadata
def _format_authors_for_bibtex(authors) -> str
def get_services() -> dict # lazy-initialises service singletons
def list_tools() -> list[Tool] # declares all MCP tools
def main() -> None # starts MCP stdio server
MCP Tools exposed:
| Tool | Description |
|---|---|
search_papers |
Search Semantic Scholar |
get_paper |
Get paper by ID |
get_context |
Read project files |
query_similar_papers |
Semantic similarity search |
add_citation |
Add BibTeX to references.bib |
get_citations |
List all citations |
save_file |
Write to project files |
get_project_status |
Project overview |
index_papers |
Build/rebuild RAG index |
init_project |
Initialise project structure |
13. FastAPI App (app.py)
def create_app() -> FastAPI:
# Registers:
# GET /health β liveness probe β {"status": "ok"}
# POST /slack/events β Bolt async handler
# Initialises Slack Bolt only if SLACK_BOT_TOKEN + SLACK_SIGNING_SECRET present
# HMAC request verification using signing_secret
14. Routing System
LLM Routing Protocol
Every LLM-enabled quant agent appends LLM_ROUTING_PROMPT to its task prompt:
After completing your analysis, decide who should be next.
Available quant roles: datafetcher, trendanalyst, sentimentanalyst,
quantresearcher, backtester, riskanalyst, quantstrategist, human
Rules:
- Choose exactly ONE role (or null if complete).
- Base your choice on what the analysis needs, not a fixed sequence.
- If uncertain or blocked, choose human.
- You cannot choose yourself.
Respond with a JSON block at the very end of your output:
{"next": "<role>", "reason": "<one sentence why>"}
or if no further action needed:
{"next": null, "reason": "Work complete."}
parse_llm_routing() extracts the last {"next": ..., "reason": ...} JSON object, validates next against QUANT_ROLES, and returns (next_role, reason, stripped_content).
Cycle Guard (V4.3)
TrendAnalyst has a hard post-parse guard:
if next_role == "datafetcher":
next_role = "sentimentanalyst" # always; log warning
Coordinator Depth Control
- Non-quant chain:
_MAX_MENTION_DEPTH = 3β hard stop β routes to@human - Quant chain: separate depth counter, pauses (not hard-stops) at limit
_ALT_AGENT_MAPβ when an agent is blocked, Coordinator can skip forward to the next stage
15. Data Flow β Full Quant Chain
1. Human sends "@datafetcher fetch MSTR MSTR" in Slack
2. SlackIntegration._process_mention()
β builds Mention(mentioned_role="datafetcher", from_role="human", content="...")
β CoordinatorService.dispatch()
3. DataFetcherAgent.handle()
β resolves watchlist: ["MSTR"]
β calls FinnhubService.fetch_ticker_data("MSTR", session_dir)
β writes quant/raw/MSTR_2026-03-26.json
β writes quant/raw/MSTR_2026-03-26_summary.md
β checks: trend_analysis_2026-03-26.md exists? No
β returns AgentResponse(mentions=["trendanalyst"])
4. CoordinatorService receives response
β publishes AgentCompletedEvent(next_role="trendanalyst", depth=1)
β dispatches Mention(mentioned_role="trendanalyst", from_role="datafetcher")
5. TrendAnalystAgent.handle()
β reads quant/raw/MSTR_2026-03-26_summary.md
β calls LLMService.complete(prompt)
β parse_llm_routing() β next_role from LLM
β cycle guard: if next_role=="datafetcher" β override to "sentimentanalyst"
β writes quant/trend_analysis_2026-03-26.md
β returns AgentResponse(mentions=["sentimentanalyst"])
6. SentimentAnalystAgent.handle() β ... β mentions=["quantresearcher"]
7. QuantResearcherAgent.handle() β ... β mentions=["backtester"]
8. BacktesterAgent.handle() β ... β mentions=["riskanalyst"]
9. RiskAnalystAgent.handle() β ... β mentions=["quantstrategist"]
10. QuantStrategistAgent.handle()
β synthesises all upstream artifacts
β produces β€3 trade proposals
β always returns mentions=["human"]
β writes quant/trade_proposals_2026-03-26.md
11. CoordinatorService posts trade proposals to Slack with approval templates
β Human reviews and responds with /approve <proposal_id>
12. (Async, scheduled) PortfolioMonitorAgent checks open positions every 30 min
β publishes PortfolioAlertEvent on threshold breach
β CoordinatorService posts alert to Slack
16. Environment Variables
| Variable | Used by | Default | Description |
|---|---|---|---|
FINNHUB_API_KEY |
FinnhubService, PortfolioMonitor | β | Finnhub API key |
ALPHAVANTAGE_API_KEY |
AlphaVantageService | β | Alpha Vantage key |
ANTHROPIC_API_KEY |
AnthropicAdapter | β | Claude API key |
GEMINI_API_KEY |
GeminiAdapter | β | Gemini API key |
SLACK_BOT_TOKEN |
SlackIntegration | β | xoxb-... bot token |
SLACK_SIGNING_SECRET |
SlackIntegration, app.py | β | Request HMAC verification |
POLYHEDRA_QUANT_WATCHLIST |
DataFetcherAgent | "" |
Comma-separated tickers e.g. MSTR,BTBT,MARA |
POLYHEDRA_VALID_TICKERS |
DataFetcherAgent | "" |
Allow-list for ticker validation; blank = regex heuristics (V4.4) |
POLYHEDRA_ENABLE_RESEARCH |
agents/__init__.py |
0 |
Set to 1 to enable Scout/Strategist/Critic/Scribe in Slack sessions (V4.4) |
POLYHEDRA_MONITOR_INTERVAL |
PortfolioMonitor | 30 |
Monitor run interval (minutes) |
POLYHEDRA_MARKET_TZ |
PortfolioMonitor | America/New_York |
Market timezone |
POLYHEDRA_ALERT_MOVE_PCT |
PortfolioMonitor | 2.0 |
Position move alert threshold (%) |
LLM_PROVIDER |
LLMService | anthropic |
Active LLM adapter (anthropic/gemini) |
LLM_MODEL |
LLMService | provider default | Model name override |
17. Key Design Patterns
Lazy LLM Initialisation (V4.3)
All 11 agents use a property-based lazy loader β LLMService() is never called at __init__ time:
def __init__(self, llm_service: LLMService | None = None) -> None:
super().__init__()
self._llm_service = llm_service
self.__llm: LLMService | None = None
@property
def _llm(self) -> LLMService:
if self.__llm is None:
self.__llm = self._llm_service or LLMService()
return self.__llm
Agent ABC Pattern
All agents inherit Agent(ABC). The Coordinator discovers agents by calling can_handle(mention) on every registered agent in the session registry until one returns True.
EventBus Transaction (V4.3)
The Coordinator subscribes to 4 event types at session creation:
AgentCompletedEventβ depth-check, state merge, chain continuationAgentBlockedEventβ skip-forward via_ALT_AGENT_MAPor escalate to humanHumanInputRequiredEventβ post templates to Slack/CLIPortfolioAlertEventβ post alert to Slack
Artifact Path Convention
All quant artifacts follow quant/<type>_<date>.md. The date is always date.today().isoformat() at run time. Same-day re-runs overwrite (mode="overwrite").
Cache-Aside with Write-Through (V4.3)
read: SharedCache.get(key) β hit: return | miss: disk.read + cache.set
write: disk.write + cache.set + rag.index_artifact
18. Known Bugs & Fixes Applied
Fix 1 β cache.py SyntaxError (V4.3 hotfix 1)
Problem: _SENTINEL := object() (walrus operator) used as default parameter in set().
Fix: Move _SENTINEL = object() to module level.
Fix 2 β slack.py duplicate channel kwarg (V4.3 hotfix 2)
Problem: _SayClient.chat_postMessage(self, _channel, ...) did not capture channel= keyword argument from callers.
Fix: Rename parameter from _channel to channel.
Fix 3 β 11Γ LLM init at startup (V4.3 hotfix 3)
Problem: All 11 agents called LLMService() eagerly in __init__, causing 11 simultaneous API client initialisations on session creation.
Fix: Lazy _llm property in all agents (see Β§17).
Fix 4 β TrendAnalyst β DataFetcher infinite loop (V4.3 hotfix 4)
Problem (two-sided):
- DataFetcher always hard-coded
next_mentions = ["trendanalyst"]after any successful fetch, even when DataFetcher was called mid-chain - TrendAnalyst LLM prompt instructed the model to route to
@datafetcheron any data gap; MSTR missing earnings always triggered this
Fixes applied (cec724c):
trendanalyst.pyβ cycle guard:
Afterparse_llm_routing, anydatafetcherroute is overridden tosentimentanalyst; warning logged.trendanalyst.pyβ prompt constraint:
Added rule: if summaries are present (DataFetcher already ran), treat remaining gaps as unavailable data and proceed to@sentimentanalystβ never route back to@datafetcher.datafetcher.pyβ smart mid-chain routing:
Checks whetherquant/trend_analysis_<today>.mdexists. If it does, DataFetcher was called mid-chain β routes tosentimentanalyst. If not, fresh session β routes totrendanalyst.
V4.4 Fixes & Structural Changes
FIX-1 β RAG session isolation (V4.4)
Problem: RAGService used a single literature/embeddings.json shared across all sessions. Embeddings from session A leaked into session B context.
Fix: RAGService.__init__ now accepts session_id; embeddings stored at ~/.polyhedra/sessions/{session_id}/embeddings.json. JSON serialisation used throughout; {} returned if file is absent.
FIX-2 β PortfolioMonitor session registry (V4.4)
Problem: _monitor_loop() iterated all sessions even those with no open positions, wasting API quota.
Fix: core/session.py gains active_sessions_with_positions(), _registry_path(), _save_registry(). _monitor_loop() filters by this set.
FIX-3 β Structured proposal output (V4.4)
Problem: _parse_proposal_block() in slack.py parsed Markdown heuristically from free text; fragile against formatting variation.
Fix: QuantStrategist's prompt now requires a fenced ```proposals ``` JSON block. parse_proposals_block() in routing.py extracts + validates it. slack.py._find_proposal_in_md() uses this function.
FIX-4 β Version 4.4.0 (V4.4)
Version strings updated in __init__.py, pyproject.toml, and app.py health endpoint.
FIX-5 β yfinance fallback β @human routing (V4.4)
Problem: _fetch_ohlcv_yfinance raised unhandled exceptions when yfinance returned errors, causing DataFetcher to crash silently.
Fix: Wrapped in try/except returning None. fetch_ticker_data() propagates has_ohlcv=False. DataFetcher tracks all_ohlcv_failed; when true, routes to @human with state_patch={"yfinance_alert": True}.
FIX-6 β Module docstrings (V4.4)
Added docstrings to agent/__init__.py and agents/__init__.py clarifying the two execution models.
FIX-7 β POLYHEDRA_ENABLE_RESEARCH flag (V4.4)
Problem: Research agents (Scout etc.) were silently excluded from Slack sessions with no opt-in mechanism.
Fix: agents/__init__.py gates research agent imports behind POLYHEDRA_ENABLE_RESEARCH=1.
FIX-8 β _is_valid_ticker() replaces _SKIP_TOKENS (V4.4)
Problem: Hardcoded frozenset of 70+ stop-words was brittle and required code changes to extend.
Fix: _is_valid_ticker(token) checks POLYHEDRA_VALID_TICKERS env var allow-list first; falls back to regex heuristics (uppercase, 1β5 chars, not in common English words).
STRUCT-1 β CoordinatorService decomposed (V4.4)
coordinator.py was ~700 lines. Four responsibilities extracted into dedicated core/ modules:
AgentRouter(core/agent_router.py) β depth tracking + routing constantsTemplateBuilder(core/template_builder.py) β input templates +COMMAND_REGISTRYStatePatcher(core/state_patcher.py) βResearchStatepatch applicationCostGate(core/cost_gate.py) β approval threshold
STRUCT-2 β Typed output models (V4.4)
agents/quant/outputs.py introduces 7 BaseModel subclasses. AgentResponse.output: BaseModel | None added; metadata deprecated.
STRUCT-3 β TraceLogger + /poly trace (V4.4)
core/trace_logger.py writes per-run entries to trace.jsonl. Coordinator injects TraceLogger into each agent. /poly trace Slack command and poly trace CLI both read the last N entries.
STRUCT-4 β COMMAND_REGISTRY + help commands (V4.4)
COMMAND_REGISTRY (25 entries) in template_builder.py. render_help_slack() and render_help_cli() render it appropriately. Exposed via /poly help (Slack) and poly help (CLI).