|
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
59.3 kB
# 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
1. [Project Overview](#1-project-overview)
2. [Repository Layout](#2-repository-layout)
3. [Package Entry Points](#3-package-entry-points)
4. [Core Infrastructure (`core/`)](#4-core-infrastructure-core)
5. [Agent System (`agents/`)](#5-agent-system-agents)
6. [Quant Pipeline (`agents/quant/`)](#6-quant-pipeline-agentsquant)
7. [Services (`services/`)](#7-services-services)
8. [Messaging (`messaging/`)](#8-messaging-messaging)
9. [CLI (`cli/`)](#9-cli-cli)
10. [Agent Workflow Engine (`agent/`)](#10-agent-workflow-engine-agent)
11. [Schemas (`schemas/`)](#11-schemas-schemas)
12. [MCP Server (`server.py`)](#12-mcp-server-serverpy)
13. [FastAPI App (`app.py`)](#13-fastapi-app-apppy)
14. [Routing System](#14-routing-system)
15. [Data Flow β Full Quant Chain](#15-data-flow--full-quant-chain)
16. [Environment Variables](#16-environment-variables)
17. [Key Design Patterns](#17-key-design-patterns)
18. [Known Bugs & Fixes Applied](#18-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`:
```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:
```python
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:**
```python
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:**
```python
_SENTINEL = object() # sentinel for "use default TTL"
prompt_hash(prompt: str) -> str # SHA-256 hex[:16] of prompt
```
> **Bug fixed:** `_SENTINEL` must 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:**
```python
@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:**
```python
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:**
```python
@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:**
```python
@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:**
```python
@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:**
```python
_CHARS_PER_TOKEN = 4
_MAX_TOKENS = 4_000
_MAX_CHARS = 16_000
```
---
### 4.5 `core/session.py` β Session Management
```python
_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`.
```python
@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`
```python
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`
```python
_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.
```python
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.
```python
@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`.
```python
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.
```python
_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).
```python
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
```python
@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):**
```python
_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` (session `trace.jsonl` writer; injected into each agent)
**CoordinatorService** drives session lifecycle. On each inbound message:
1. Parses @mentions via `MentionParser`
2. Assembles `Mention` with `from_role`, `thread_message_id`
3. Calls `self._router.can_dispatch()` + `record_dispatch()` + `init_origin()`
4. Finds matching agent via `RoleRegistry`; injects `entry.agent.trace = self._trace`
5. Calls `agent.handle()` inside an event-bus transaction
6. Publishes `AgentCompletedEvent` / `AgentBlockedEvent` / `HumanInputRequiredEvent`
7. Depth-tracks via `AgentRouter`; pauses (not hard-stops) at limit for quant chain
8. Applies `state_patch` via `self._patcher.apply()`
9. 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()` from `TemplateBuilder`
**`_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:
```python
@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
```python
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_WATCHLIST` env
- Calls `FinnhubService.fetch_ticker_data()` per ticker
- Writes `quant/raw/<TICKER>_<date>.json` and `quant/raw/<TICKER>_<date>_summary.md`
- **Routing logic (V4.4):**
```python
# _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 against `POLYHEDRA_VALID_TICKERS` env 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.md` files written by DataFetcher
- If no summaries exist β returns `AgentResponse(mentions=["datafetcher"])`
- LLM call β `parse_llm_routing`
- **Cycle guard (V4.3):** forcibly overrides any `datafetcher` routing to `sentimentanalyst`
```python
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. `[1] ROLE` β system prompt
2. `[2] INPUTS` β tickers + raw summaries (capped 4000 chars) + thread context
3. `[3] TASK` β per-ticker sections: price trend, volume, momentum, earnings
4. `[4] CONSTRAINTS` β ETF rule, data gap rule, **datafetcher cycle guard rule**
5. `[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, route `datafetcher`
- `_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()` from `routing.py` extracts 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 `matplotlib` for static PNG generation
- LLM generates a 2β3 sentence chart caption
---
### 6.11 PortfolioMonitorAgent (`portfoliomonitor.py`)
- **Schedule:** every `POLYHEDRA_MONITOR_INTERVAL` minutes (default 30), MonβFri 09:30β16:00 ET
- **`_DEFAULT_ALERT_MOVE_PCT = 2.0`** β threshold for unrealised move alerts
- On each run:
1. Fetches latest quote for every open position via `FinnhubService.get_quote()`
2. Evaluates take-profit, stop-loss, Β±move thresholds
3. Publishes `PortfolioAlertEvent` on breach
4. Writes `quant/portfolio_log_<date>.md`
- **`_is_market_hours(tz_name)`** β checks MonβFri 09:30β16:00 in given timezone; graceful fallback if `zoneinfo` unavailable
**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).
```python
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:**
```python
ConfigurationError # missing API key or config
RateLimitError # HTTP 429; carries retry_after: int | None
AuthenticationError # 401/403
TimeoutError # request timeout
```
**Abstract adapter:**
```python
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:**
```python
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:
```python
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.
```python
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.
```python
_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_yfinance` is now wrapped in `try/except`, returning `None` on any exception. `fetch_ticker_data()` checks for `None` and sets `has_ohlcv=False` in the returned tuple; DataFetcher uses `all_ohlcv_failed` to route to `@human` with `yfinance_alert: True`.
---
### 7.4 `services/alpha_vantage.py`
```python
_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)
```python
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`
```python
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`
```python
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`
```python
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:
```python
{
"datafetcher": "DataFetcher π",
"trendanalyst": "TrendAnalyst π",
"sentimentanalyst": "SentimentAnalyst π°",
"quantresearcher": "QuantResearcher π¬",
"backtester": "Backtester β±οΈ",
"riskanalyst": "RiskAnalyst β οΈ",
"quantstrategist": "QuantStrategist π―",
"vizagent": "VizAgent π",
"portfoliomonitor": "PortfolioMonitor π",
# ... research agents
}
```
**SlackIntegration:**
```python
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:
```python
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_postMessage` had duplicate `channel` kwarg β renamed positional param from `_channel` to `channel`.
---
## 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:**
```python
_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`
```python
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`
```python
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`
```python
@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`
```python
@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`
```python
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`
```python
@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:
```python
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**.
```python
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`)
```python
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:
```python
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:
```python
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 continuation
- `AgentBlockedEvent` β skip-forward via `_ALT_AGENT_MAP` or escalate to human
- `HumanInputRequiredEvent` β post templates to Slack/CLI
- `PortfolioAlertEvent` β 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 `@datafetcher` on any data gap; MSTR missing earnings always triggered this
**Fixes applied (`cec724c`):**
1. **`trendanalyst.py` β cycle guard:**
After `parse_llm_routing`, any `datafetcher` route is overridden to `sentimentanalyst`; warning logged.
2. **`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`.
3. **`datafetcher.py` β smart mid-chain routing:**
Checks whether `quant/trend_analysis_<today>.md` exists. If it does, DataFetcher was called mid-chain β routes to `sentimentanalyst`. If not, fresh session β routes to `trendanalyst`.
---
## 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 constants
- `TemplateBuilder` (`core/template_builder.py`) β input templates + `COMMAND_REGISTRY`
- `StatePatcher` (`core/state_patcher.py`) β `ResearchState` patch application
- `CostGate` (`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).
# 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
1. [Project Overview](#1-project-overview)
2. [Repository Layout](#2-repository-layout)
3. [Package Entry Points](#3-package-entry-points)
4. [Core Infrastructure (`core/`)](#4-core-infrastructure-core)
5. [Agent System (`agents/`)](#5-agent-system-agents)
6. [Quant Pipeline (`agents/quant/`)](#6-quant-pipeline-agentsquant)
7. [Services (`services/`)](#7-services-services)
8. [Messaging (`messaging/`)](#8-messaging-messaging)
9. [CLI (`cli/`)](#9-cli-cli)
10. [Agent Workflow Engine (`agent/`)](#10-agent-workflow-engine-agent)
11. [Schemas (`schemas/`)](#11-schemas-schemas)
12. [MCP Server (`server.py`)](#12-mcp-server-serverpy)
13. [FastAPI App (`app.py`)](#13-fastapi-app-apppy)
14. [Routing System](#14-routing-system)
15. [Data Flow β Full Quant Chain](#15-data-flow--full-quant-chain)
16. [Environment Variables](#16-environment-variables)
17. [Key Design Patterns](#17-key-design-patterns)
18. [Known Bugs & Fixes Applied](#18-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)