feat: V4.3 — SharedCache, EventBus, RAG layer, Token Budgeting
Browse files- core/cache.py: SharedCache with TTL, disk flush, cache-first reads
- core/eventbus.py: in-process pub/sub (AgentCompleted/Blocked/HumanInput/PortfolioAlert events)
- core/token_budget.py: TokenBudget + PromptBuilder per-agent token enforcement
- core/research_state.py: TokenUsageEntry dataclass, QuantState.token_log deserialization
- services/file_writer.py: cache-first reads, RAG auto-index on writes
- services/rag_service.py: index_artifact, query_artifacts, rebuild_artifact_index_from_disk
- agents/base.py: bus + token_budget attributes, _log_token_usage() helper
- agents/coordinator.py: full EventBus refactor, slash commands (/poly cache, /poly tokens), event handlers
- agents/quant/*: TokenBudget declaration + token logging on all LLM-calling agents
- agents/quant/portfoliomonitor.py: emits PortfolioAlertEvent on threshold breach
- cli/main.py: poly cache and poly tokens subcommands
- core/__init__.py: exports SharedCache, EventBus, TokenBudget, TokenUsageEntry, all event types
- .env.example +12 -0
- docs/polyhedraV4.3.md +344 -0
- src/polyhedra/agents/base.py +40 -1
- src/polyhedra/agents/coordinator.py +245 -42
- src/polyhedra/agents/quant/backtester.py +8 -1
- src/polyhedra/agents/quant/portfoliomonitor.py +32 -0
- src/polyhedra/agents/quant/quantresearcher.py +9 -2
- src/polyhedra/agents/quant/quantstrategist.py +8 -1
- src/polyhedra/agents/quant/riskanalyst.py +9 -2
- src/polyhedra/agents/quant/sentimentanalyst.py +9 -2
- src/polyhedra/agents/quant/trendanalyst.py +9 -3
- src/polyhedra/agents/quant/vizagent.py +6 -1
- src/polyhedra/cli/main.py +70 -0
- src/polyhedra/core/__init__.py +22 -2
- src/polyhedra/core/cache.py +242 -0
- src/polyhedra/core/eventbus.py +189 -0
- src/polyhedra/core/research_state.py +18 -0
- src/polyhedra/core/token_budget.py +235 -0
- src/polyhedra/services/file_writer.py +125 -12
- src/polyhedra/services/rag_service.py +141 -0
|
@@ -58,6 +58,18 @@ POLYHEDRA_MAX_COST=1.00
|
|
| 58 |
|
| 59 |
# Signing secret — from your Slack app's "Basic Information" page
|
| 60 |
# SLACK_SIGNING_SECRET=your-signing-secret-here
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 61 |
# =============================================================================
|
| 62 |
# Usage Notes
|
| 63 |
# =============================================================================
|
|
|
|
| 58 |
|
| 59 |
# Signing secret — from your Slack app's "Basic Information" page
|
| 60 |
# SLACK_SIGNING_SECRET=your-signing-secret-here
|
| 61 |
+
|
| 62 |
+
# =============================================================================
|
| 63 |
+
# Finnhub — Market Data (v4.0 quant team / paper trading)
|
| 64 |
+
# =============================================================================
|
| 65 |
+
|
| 66 |
+
# Required for /poly quant, /poly portfolio, /poly trade, /poly watchlist
|
| 67 |
+
# Free tier: 60 API calls/minute — get your key at: https://finnhub.io/dashboard
|
| 68 |
+
# FINNHUB_API_KEY=your-key-here
|
| 69 |
+
|
| 70 |
+
# Seed watchlist (optional, comma-separated tickers)
|
| 71 |
+
# Users can also manage the watchlist live via /poly watchlist add <TICKER>
|
| 72 |
+
# POLYHEDRA_QUANT_WATCHLIST=AAPL,MSFT,NVDA,GOOGL
|
| 73 |
# =============================================================================
|
| 74 |
# Usage Notes
|
| 75 |
# =============================================================================
|
|
@@ -0,0 +1,344 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Polyhedra V4.3 — PRD (Infrastructure)
|
| 2 |
+
|
| 3 |
+
> Pure infrastructure release. No new agents, no new user-facing features. Replaces the underlying communication and memory plumbing with a more efficient model while preserving all agent behavior from V4.0–V4.2.
|
| 4 |
+
|
| 5 |
+
---
|
| 6 |
+
|
| 7 |
+
## Philosophy
|
| 8 |
+
|
| 9 |
+
Agents still collaborate like a human team — they read each other's work, reason about it, decide who to involve next, and write structured outputs. V4.3 replaces *how* that collaboration is plumbed:
|
| 10 |
+
|
| 11 |
+
| Before V4.3 | After V4.3 |
|
| 12 |
+
|---|---|
|
| 13 |
+
| Coordinator directly dispatches agents | Agents emit events, Coordinator reacts as subscriber |
|
| 14 |
+
| Agents read artifacts from disk on every invocation | Agents read from shared in-memory cache |
|
| 15 |
+
| Full artifact content injected into every prompt | RAG retrieves only the relevant slice per prompt |
|
| 16 |
+
| No LLM output reuse | Identical prompts return cached LLM responses |
|
| 17 |
+
| `research_state.json` file as shared state | Cache is the shared state layer; file is persistence backup only |
|
| 18 |
+
|
| 19 |
+
Agent reasoning, routing decisions, artifact ownership, and human touchpoints are all unchanged.
|
| 20 |
+
|
| 21 |
+
---
|
| 22 |
+
|
| 23 |
+
## Overview
|
| 24 |
+
|
| 25 |
+
V4.3 delivers four infrastructure improvements:
|
| 26 |
+
|
| 27 |
+
1. **Shared Cache** — replaces file-based shared state with an in-memory cache layer
|
| 28 |
+
2. **EventBus** — replaces direct Coordinator dispatch with a publish/subscribe event system
|
| 29 |
+
3. **RAG Layer** — activates and extends `rag_service.py` for the quant team; agents retrieve relevant context rather than loading full artifacts
|
| 30 |
+
4. **Token Budgeting** — agents declare a token budget; prompt builder enforces it by selectively injecting only what fits
|
| 31 |
+
|
| 32 |
+
---
|
| 33 |
+
|
| 34 |
+
## 1. Shared Cache
|
| 35 |
+
|
| 36 |
+
### Problem
|
| 37 |
+
Every agent invocation currently reads `research_state.json` and all required artifact files from disk. On a 7-agent quant run this means repeated deserialization of the same files, stale reads if a prior agent hasn't flushed yet, and no way to share intermediate state without writing a full artifact.
|
| 38 |
+
|
| 39 |
+
### Solution
|
| 40 |
+
A shared in-memory cache that is the primary state layer for all agents during a session. The filesystem becomes a persistence backup only — written asynchronously, never read during a live chain.
|
| 41 |
+
|
| 42 |
+
### Design
|
| 43 |
+
|
| 44 |
+
```python
|
| 45 |
+
class SharedCache:
|
| 46 |
+
def get(key: str) -> Any | None
|
| 47 |
+
def set(key: str, value: Any, ttl: int | None = None) -> None
|
| 48 |
+
def invalidate(key: str) -> None
|
| 49 |
+
def invalidate_prefix(prefix: str) -> None
|
| 50 |
+
def flush_to_disk(session_dir: str) -> None # async, called by Coordinator
|
| 51 |
+
```
|
| 52 |
+
|
| 53 |
+
**Cache key conventions:**
|
| 54 |
+
```
|
| 55 |
+
state:<session_id> # QuantState / ResearchState
|
| 56 |
+
artifact:<session_id>:<path> # artifact contents, keyed by path
|
| 57 |
+
llm:<prompt_hash> # LLM output, keyed by prompt hash
|
| 58 |
+
api:<provider>:<endpoint>:<params> # API responses, keyed by call signature
|
| 59 |
+
```
|
| 60 |
+
|
| 61 |
+
**Scope:** Per-process, shared across all agents within a session. Not shared across sessions or Slack channels.
|
| 62 |
+
|
| 63 |
+
### Requirements
|
| 64 |
+
|
| 65 |
+
**FR-1.1** All agent reads of `ResearchState` / `QuantState` must go through the cache. Direct file reads are prohibited during a live chain.
|
| 66 |
+
|
| 67 |
+
**FR-1.2** `FileWriter.write()` must update the cache on every write in addition to writing to disk. Cache and disk are always in sync after a write.
|
| 68 |
+
|
| 69 |
+
**FR-1.3** `FileWriter.read()` must check the cache first. On cache miss, read from disk and populate the cache before returning.
|
| 70 |
+
|
| 71 |
+
**FR-1.4** API response cache (`api:*`) uses TTL-based expiry:
|
| 72 |
+
- Market data (OHLCV, indicators): TTL = 24 hours
|
| 73 |
+
- News sentiment: TTL = 1 hour
|
| 74 |
+
- Real-time quotes (PortfolioMonitor): TTL = 1 minute
|
| 75 |
+
|
| 76 |
+
**FR-1.5** LLM output cache (`llm:*`) is keyed by a hash of the full prompt string. On cache hit, the cached response is returned without making an API call. TTL = session lifetime (never expires mid-session).
|
| 77 |
+
|
| 78 |
+
**FR-1.6** Cache is invalidated on `DataFetcher` write — all `artifact:*` keys for affected tickers are dropped, forcing downstream agents to re-read fresh data.
|
| 79 |
+
|
| 80 |
+
**FR-1.7** Cache is per-session isolated — no cross-session reads or writes.
|
| 81 |
+
|
| 82 |
+
**FR-1.8** `/poly cache clear` flushes the in-memory cache for the current session and forces a reload from disk on next access.
|
| 83 |
+
|
| 84 |
+
**FR-1.9** On container restart, cache is cold. Agents fall back to disk reads seamlessly via `FileWriter.read()`.
|
| 85 |
+
|
| 86 |
+
### New Slash Command
|
| 87 |
+
| Command | Action |
|
| 88 |
+
|---|---|
|
| 89 |
+
| `/poly cache clear` | Flush session cache, reload from disk on next access |
|
| 90 |
+
| `/poly cache status` | Show cache hit/miss stats for current session |
|
| 91 |
+
|
| 92 |
+
---
|
| 93 |
+
|
| 94 |
+
## 2. EventBus
|
| 95 |
+
|
| 96 |
+
### Problem
|
| 97 |
+
The Coordinator currently dispatches agents via direct function calls — it reads `AgentResponse.mentions`, looks up the agent, and calls `agent.handle()` synchronously. This creates tight coupling: the Coordinator must know about every agent, the call stack grows with chain depth, and there is no clean way to react to agent events from outside the dispatch loop (e.g. the PortfolioMonitor alerting while a chain is running).
|
| 98 |
+
|
| 99 |
+
### Solution
|
| 100 |
+
A lightweight publish/subscribe EventBus. Agents emit events when they complete, are blocked, or need human input. The Coordinator subscribes to these events and reacts — but is no longer in the direct call path.
|
| 101 |
+
|
| 102 |
+
### Event Types
|
| 103 |
+
|
| 104 |
+
```python
|
| 105 |
+
@dataclass
|
| 106 |
+
class AgentCompletedEvent:
|
| 107 |
+
session_id: str
|
| 108 |
+
agent_role: str
|
| 109 |
+
artifact_path: str | None
|
| 110 |
+
next_role: str | None # from routing JSON
|
| 111 |
+
reason: str
|
| 112 |
+
depth: int
|
| 113 |
+
|
| 114 |
+
@dataclass
|
| 115 |
+
class AgentBlockedEvent:
|
| 116 |
+
session_id: str
|
| 117 |
+
agent_role: str
|
| 118 |
+
reason: str
|
| 119 |
+
missing_artifact: str | None
|
| 120 |
+
suggested_role: str | None
|
| 121 |
+
|
| 122 |
+
@dataclass
|
| 123 |
+
class HumanInputRequiredEvent:
|
| 124 |
+
session_id: str
|
| 125 |
+
agent_role: str
|
| 126 |
+
question: str
|
| 127 |
+
suggested_templates: list[str]
|
| 128 |
+
|
| 129 |
+
@dataclass
|
| 130 |
+
class PortfolioAlertEvent:
|
| 131 |
+
session_id: str
|
| 132 |
+
position_id: str
|
| 133 |
+
ticker: str
|
| 134 |
+
alert_type: str # "take_profit" | "stop_loss" | "pct_move"
|
| 135 |
+
current_price: float
|
| 136 |
+
threshold: float
|
| 137 |
+
```
|
| 138 |
+
|
| 139 |
+
### Design
|
| 140 |
+
|
| 141 |
+
```python
|
| 142 |
+
class EventBus:
|
| 143 |
+
def publish(event: Any) -> None
|
| 144 |
+
def subscribe(event_type: type, handler: Callable) -> None
|
| 145 |
+
def unsubscribe(event_type: type, handler: Callable) -> None
|
| 146 |
+
```
|
| 147 |
+
|
| 148 |
+
**Coordinator as subscriber:**
|
| 149 |
+
```python
|
| 150 |
+
bus.subscribe(AgentCompletedEvent, coordinator.on_agent_completed)
|
| 151 |
+
bus.subscribe(AgentBlockedEvent, coordinator.on_agent_blocked)
|
| 152 |
+
bus.subscribe(HumanInputRequiredEvent, coordinator.on_human_input_required)
|
| 153 |
+
bus.subscribe(PortfolioAlertEvent, coordinator.on_portfolio_alert)
|
| 154 |
+
```
|
| 155 |
+
|
| 156 |
+
**Agent emit pattern:**
|
| 157 |
+
```python
|
| 158 |
+
# Inside agent.handle() — after writing artifact and parsing routing JSON
|
| 159 |
+
await bus.publish(AgentCompletedEvent(
|
| 160 |
+
session_id=self.session_id,
|
| 161 |
+
agent_role=self.role,
|
| 162 |
+
artifact_path=artifact_path,
|
| 163 |
+
next_role=routing["next"],
|
| 164 |
+
reason=routing["reason"],
|
| 165 |
+
depth=current_depth
|
| 166 |
+
))
|
| 167 |
+
```
|
| 168 |
+
|
| 169 |
+
### Requirements
|
| 170 |
+
|
| 171 |
+
**FR-2.1** All agent-to-agent routing must go through the EventBus. Direct agent calls from the Coordinator are removed.
|
| 172 |
+
|
| 173 |
+
**FR-2.2** The Coordinator subscribes to all event types at session init. It remains the sole orchestrator — agents do not subscribe to each other's events directly.
|
| 174 |
+
|
| 175 |
+
**FR-2.3** Depth tracking moves into the Coordinator's `on_agent_completed` handler. The depth counter is incremented on every `AgentCompletedEvent` and checked before dispatching the next agent.
|
| 176 |
+
|
| 177 |
+
**FR-2.4** `PortfolioAlertEvent` is published by `PortfolioMonitorAgent` independently of the main chain. The Coordinator handles it without interrupting any running chain.
|
| 178 |
+
|
| 179 |
+
**FR-2.5** The EventBus is in-process and synchronous in V4.3 — no message queue or external broker. Async support is a future consideration.
|
| 180 |
+
|
| 181 |
+
**FR-2.6** If a handler raises an exception, the EventBus catches it, logs it, and does not propagate to other subscribers.
|
| 182 |
+
|
| 183 |
+
---
|
| 184 |
+
|
| 185 |
+
## 3. RAG Layer
|
| 186 |
+
|
| 187 |
+
### Problem
|
| 188 |
+
Agents currently receive full artifact contents injected into their prompts. On a multi-day session with accumulated signals, backtest results, and risk assessments, this grows beyond useful context window size and inflates token usage on every invocation.
|
| 189 |
+
|
| 190 |
+
### Solution
|
| 191 |
+
Activate and extend the existing `rag_service.py` for the quant team. Agents declare what context they need; RAG retrieves the most relevant chunks rather than full files.
|
| 192 |
+
|
| 193 |
+
### Design
|
| 194 |
+
|
| 195 |
+
`RagService` is extended with quant-specific indexing:
|
| 196 |
+
|
| 197 |
+
```python
|
| 198 |
+
class RagService:
|
| 199 |
+
def index(path: str, content: str, metadata: dict) -> None
|
| 200 |
+
# Called by FileWriter.write() automatically on every artifact write
|
| 201 |
+
|
| 202 |
+
def query(question: str, top_k: int = 5, filter: dict = None) -> list[Chunk]
|
| 203 |
+
# Returns top_k most relevant chunks, optionally filtered by metadata
|
| 204 |
+
# filter examples: {"agent_role": "quantresearcher"}, {"ticker": "GLD"}
|
| 205 |
+
```
|
| 206 |
+
|
| 207 |
+
**Automatic indexing:** `FileWriter.write()` calls `rag_service.index()` on every artifact write. No agent needs to manually index its output.
|
| 208 |
+
|
| 209 |
+
**Agent query pattern:** Each agent's prompt builder calls `rag_service.query()` to retrieve relevant context instead of loading full artifacts:
|
| 210 |
+
|
| 211 |
+
```python
|
| 212 |
+
# TrendAnalystAgent prompt builder
|
| 213 |
+
chunks = rag.query(
|
| 214 |
+
question=f"OHLCV and indicator data for {ticker}",
|
| 215 |
+
top_k=5,
|
| 216 |
+
filter={"ticker": ticker, "date": today}
|
| 217 |
+
)
|
| 218 |
+
# Injects only retrieved chunks into prompt, not full raw JSON
|
| 219 |
+
```
|
| 220 |
+
|
| 221 |
+
### Requirements
|
| 222 |
+
|
| 223 |
+
**FR-3.1** `FileWriter.write()` must index every artifact write into `RagService` automatically. Agents do not call `rag_service.index()` directly.
|
| 224 |
+
|
| 225 |
+
**FR-3.2** Each agent's prompt builder must use `RagService.query()` for artifact context retrieval. Full artifact injection is removed from all agent prompts.
|
| 226 |
+
|
| 227 |
+
**FR-3.3** RAG index is per-session. Cross-session retrieval is not supported in V4.3.
|
| 228 |
+
|
| 229 |
+
**FR-3.4** Index is rebuilt from disk artifacts on container restart (cold start recovery).
|
| 230 |
+
|
| 231 |
+
**FR-3.5** Chunk metadata must include at minimum: `session_id`, `agent_role`, `ticker` (if applicable), `artifact_path`, `date`.
|
| 232 |
+
|
| 233 |
+
**FR-3.6** RAG retrieval results are cached under `llm:<query_hash>` in the SharedCache with TTL = 5 minutes.
|
| 234 |
+
|
| 235 |
+
---
|
| 236 |
+
|
| 237 |
+
## 4. Token Budgeting
|
| 238 |
+
|
| 239 |
+
### Problem
|
| 240 |
+
No agent currently has any awareness of how many tokens it is consuming. On large watchlists or long sessions, prompts can silently grow to the point of hitting context limits or generating unexpectedly high costs.
|
| 241 |
+
|
| 242 |
+
### Solution
|
| 243 |
+
Each agent declares a token budget. The prompt builder enforces it by prioritising and trimming context to fit within the budget before making the LLM call.
|
| 244 |
+
|
| 245 |
+
### Design
|
| 246 |
+
|
| 247 |
+
Each agent class declares:
|
| 248 |
+
```python
|
| 249 |
+
class TrendAnalystAgent(Agent):
|
| 250 |
+
token_budget = TokenBudget(
|
| 251 |
+
system=500, # role + constraints block
|
| 252 |
+
context=2000, # RAG-retrieved artifact chunks
|
| 253 |
+
task=500, # task instruction block
|
| 254 |
+
thread=500, # last N thread messages
|
| 255 |
+
routing=200, # routing block
|
| 256 |
+
total=4000 # hard ceiling
|
| 257 |
+
)
|
| 258 |
+
```
|
| 259 |
+
|
| 260 |
+
The prompt builder enforces the budget:
|
| 261 |
+
1. Allocates tokens to each section in order of priority: `system` → `task` → `routing` → `context` → `thread`
|
| 262 |
+
2. If `context` chunks exceed their allocation, the lowest-scoring RAG chunks are dropped first
|
| 263 |
+
3. If total still exceeds `total`, `thread` is trimmed (oldest messages first)
|
| 264 |
+
4. Never trims `system`, `task`, or `routing` — these are always injected in full
|
| 265 |
+
|
| 266 |
+
### Requirements
|
| 267 |
+
|
| 268 |
+
**FR-4.1** Every agent must declare a `TokenBudget`. Default budget if undeclared: 4000 tokens total.
|
| 269 |
+
|
| 270 |
+
**FR-4.2** `LLMService.complete()` must receive a pre-built, budget-enforced prompt. Token counting uses `LLMService.estimate_tokens()`.
|
| 271 |
+
|
| 272 |
+
**FR-4.3** If a prompt cannot fit within budget even after trimming, the agent must emit `AgentBlockedEvent` with reason "prompt exceeds token budget" rather than sending an oversized prompt.
|
| 273 |
+
|
| 274 |
+
**FR-4.4** Token usage per agent invocation is logged to `QuantState.token_log` for cost tracking:
|
| 275 |
+
```python
|
| 276 |
+
@dataclass
|
| 277 |
+
class TokenUsageEntry:
|
| 278 |
+
agent_role: str
|
| 279 |
+
timestamp: str
|
| 280 |
+
prompt_tokens: int
|
| 281 |
+
completion_tokens: int
|
| 282 |
+
estimated_cost_usd: float
|
| 283 |
+
cache_hit: bool # True if LLM cache was used
|
| 284 |
+
```
|
| 285 |
+
|
| 286 |
+
**FR-4.5** `/poly tokens` posts a session token usage summary to Slack, broken down by agent.
|
| 287 |
+
|
| 288 |
+
### New Slash Command
|
| 289 |
+
| Command | Action |
|
| 290 |
+
|---|---|
|
| 291 |
+
| `/poly tokens` | Show session token usage and estimated cost by agent |
|
| 292 |
+
|
| 293 |
+
---
|
| 294 |
+
|
| 295 |
+
## New Environment Variables
|
| 296 |
+
|
| 297 |
+
```
|
| 298 |
+
POLYHEDRA_CACHE_TTL_MARKET TTL for market data cache in seconds (default: 86400)
|
| 299 |
+
POLYHEDRA_CACHE_TTL_SENTIMENT TTL for sentiment cache in seconds (default: 3600)
|
| 300 |
+
POLYHEDRA_CACHE_TTL_QUOTE TTL for real-time quote cache in seconds (default: 60)
|
| 301 |
+
```
|
| 302 |
+
|
| 303 |
+
---
|
| 304 |
+
|
| 305 |
+
## Implementation Checklist
|
| 306 |
+
|
| 307 |
+
### Shared Cache
|
| 308 |
+
- [ ] `SharedCache` class — `src/polyhedra/core/cache.py`
|
| 309 |
+
- [ ] `FileWriter.read()` — cache-first with disk fallback
|
| 310 |
+
- [ ] `FileWriter.write()` — writes to cache and disk simultaneously
|
| 311 |
+
- [ ] TTL enforcement per cache key prefix
|
| 312 |
+
- [ ] LLM output caching keyed by prompt hash
|
| 313 |
+
- [ ] Cache invalidation on `DataFetcherAgent` write
|
| 314 |
+
- [ ] `/poly cache clear` and `/poly cache status` commands
|
| 315 |
+
|
| 316 |
+
### EventBus
|
| 317 |
+
- [ ] `EventBus` class — `src/polyhedra/core/eventbus.py`
|
| 318 |
+
- [ ] All event dataclasses defined
|
| 319 |
+
- [ ] Coordinator refactored — direct dispatch removed, event handlers added
|
| 320 |
+
- [ ] All agents updated — emit `AgentCompletedEvent` / `AgentBlockedEvent` / `HumanInputRequiredEvent`
|
| 321 |
+
- [ ] `PortfolioMonitorAgent` emits `PortfolioAlertEvent`
|
| 322 |
+
- [ ] Depth tracking moved into `on_agent_completed` handler
|
| 323 |
+
|
| 324 |
+
### RAG Layer
|
| 325 |
+
- [ ] `RagService` extended — `src/polyhedra/services/rag_service.py`
|
| 326 |
+
- [ ] `FileWriter.write()` calls `rag_service.index()` on every write
|
| 327 |
+
- [ ] All agent prompt builders updated — full artifact injection replaced with RAG query
|
| 328 |
+
- [ ] Cold start index rebuild from disk artifacts
|
| 329 |
+
- [ ] RAG query results cached in `SharedCache`
|
| 330 |
+
|
| 331 |
+
### Token Budgeting
|
| 332 |
+
- [ ] `TokenBudget` dataclass — `src/polyhedra/core/token_budget.py`
|
| 333 |
+
- [ ] Prompt builder enforces budget per section priority
|
| 334 |
+
- [ ] `TokenUsageEntry` dataclass + `QuantState.token_log`
|
| 335 |
+
- [ ] `LLMService.complete()` logs token usage post-call
|
| 336 |
+
- [ ] `/poly tokens` command
|
| 337 |
+
|
| 338 |
+
---
|
| 339 |
+
|
| 340 |
+
## Out of Scope for V4.3
|
| 341 |
+
- Async / distributed EventBus (message queue, Redis pub/sub) — future
|
| 342 |
+
- Cross-session RAG retrieval — future
|
| 343 |
+
- Real-time token usage alerts — future
|
| 344 |
+
- Research pipeline infrastructure updates — postponed indefinitely
|
|
@@ -1,4 +1,4 @@
|
|
| 1 |
-
"""Agent base class and shared data models for Polyhedra v4.
|
| 2 |
|
| 3 |
from __future__ import annotations
|
| 4 |
|
|
@@ -9,6 +9,8 @@ from datetime import datetime, timezone
|
|
| 9 |
from typing import TYPE_CHECKING, Any
|
| 10 |
|
| 11 |
if TYPE_CHECKING:
|
|
|
|
|
|
|
| 12 |
from polyhedra.services.file_writer import FileWriter
|
| 13 |
|
| 14 |
|
|
@@ -61,6 +63,10 @@ class Agent(ABC):
|
|
| 61 |
# V4.1: injected by Coordinator before handle() — do not set in agent __init__
|
| 62 |
files: FileWriter # type: ignore[name-defined]
|
| 63 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 64 |
def __init__(self) -> None:
|
| 65 |
self.logger = logging.getLogger(f"polyhedra.agents.{self.role}")
|
| 66 |
|
|
@@ -122,3 +128,36 @@ class Agent(ABC):
|
|
| 122 |
if open_q:
|
| 123 |
lines.append("**Open questions:** " + "; ".join(str(q) for q in open_q))
|
| 124 |
return "\n".join(lines)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""Agent base class and shared data models for Polyhedra v4.3."""
|
| 2 |
|
| 3 |
from __future__ import annotations
|
| 4 |
|
|
|
|
| 9 |
from typing import TYPE_CHECKING, Any
|
| 10 |
|
| 11 |
if TYPE_CHECKING:
|
| 12 |
+
from polyhedra.core.eventbus import EventBus
|
| 13 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 14 |
from polyhedra.services.file_writer import FileWriter
|
| 15 |
|
| 16 |
|
|
|
|
| 63 |
# V4.1: injected by Coordinator before handle() — do not set in agent __init__
|
| 64 |
files: FileWriter # type: ignore[name-defined]
|
| 65 |
|
| 66 |
+
# V4.3: injected by Coordinator before handle()
|
| 67 |
+
bus: "EventBus | None" = None # EventBus for publishing completion events
|
| 68 |
+
token_budget: "TokenBudget | None" = None # per-agent budget; None = use DEFAULT_BUDGET
|
| 69 |
+
|
| 70 |
def __init__(self) -> None:
|
| 71 |
self.logger = logging.getLogger(f"polyhedra.agents.{self.role}")
|
| 72 |
|
|
|
|
| 128 |
if open_q:
|
| 129 |
lines.append("**Open questions:** " + "; ".join(str(q) for q in open_q))
|
| 130 |
return "\n".join(lines)
|
| 131 |
+
|
| 132 |
+
def _log_token_usage(
|
| 133 |
+
self,
|
| 134 |
+
research_state: dict[str, Any],
|
| 135 |
+
prompt_tokens: int,
|
| 136 |
+
completion_tokens: int,
|
| 137 |
+
*,
|
| 138 |
+
cache_hit: bool = False,
|
| 139 |
+
estimated_cost_usd: float = 0.0,
|
| 140 |
+
) -> None:
|
| 141 |
+
"""
|
| 142 |
+
Append a TokenUsageEntry to QuantState.token_log (V4.3 FR-4.4).
|
| 143 |
+
|
| 144 |
+
No-op if the research state has no quant_state.
|
| 145 |
+
"""
|
| 146 |
+
from datetime import datetime, timezone
|
| 147 |
+
from polyhedra.core.research_state import TokenUsageEntry
|
| 148 |
+
|
| 149 |
+
qs_dict = research_state.get("quant_state")
|
| 150 |
+
if not isinstance(qs_dict, dict):
|
| 151 |
+
return
|
| 152 |
+
|
| 153 |
+
entry = TokenUsageEntry(
|
| 154 |
+
agent_role=self.role,
|
| 155 |
+
timestamp=datetime.now(tz=timezone.utc).isoformat(),
|
| 156 |
+
prompt_tokens=prompt_tokens,
|
| 157 |
+
completion_tokens=completion_tokens,
|
| 158 |
+
estimated_cost_usd=estimated_cost_usd,
|
| 159 |
+
cache_hit=cache_hit,
|
| 160 |
+
)
|
| 161 |
+
token_log = qs_dict.setdefault("token_log", [])
|
| 162 |
+
from dataclasses import asdict as _asdict
|
| 163 |
+
token_log.append(_asdict(entry))
|
|
@@ -4,6 +4,11 @@ The Coordinator is always active. It is the entry point for every message:
|
|
| 4 |
it parses @mentions, routes tasks to agents or the human, maintains the
|
| 5 |
Research State, fires checkpoint gates, and detects @mention loops.
|
| 6 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 7 |
This module also exposes the top-level ``CoordinatorService`` which drives an
|
| 8 |
entire session (CLI or Slack webhook).
|
| 9 |
"""
|
|
@@ -17,12 +22,19 @@ from dataclasses import dataclass, field
|
|
| 17 |
from typing import Any, Callable, Awaitable
|
| 18 |
|
| 19 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 20 |
from polyhedra.core.mention_parser import MentionParser
|
| 21 |
from polyhedra.core.research_state import ResearchStateManager, Paper, Gap, Decision, Hypothesis
|
| 22 |
from polyhedra.core.role_registry import RoleRegistry, RoleEntry, HELD_BY_AGENT, HELD_BY_HUMAN
|
| 23 |
from polyhedra.core.session import Session
|
| 24 |
from polyhedra.services.file_writer import FileWriter
|
| 25 |
from polyhedra.services.llm_service import LLMService
|
|
|
|
| 26 |
|
| 27 |
logger = logging.getLogger(__name__)
|
| 28 |
|
|
@@ -250,6 +262,17 @@ class CoordinatorService:
|
|
| 250 |
self._mention_depth: dict[str, int] = {} # keyed by originating message_id
|
| 251 |
self._quant_mention_depth: dict[str, int] = {} # separate counter for quant chain
|
| 252 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 253 |
# ------------------------------------------------------------------ #
|
| 254 |
# Public API
|
| 255 |
# ------------------------------------------------------------------ #
|
|
@@ -258,10 +281,15 @@ class CoordinatorService:
|
|
| 258 |
"""
|
| 259 |
Entry point for every incoming message.
|
| 260 |
|
| 261 |
-
|
| 262 |
-
2. Parses @mentions.
|
| 263 |
-
3. For each mention: checks loop depth, then routes.
|
| 264 |
"""
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 265 |
msg = self.session.post(from_role=from_role, content=text)
|
| 266 |
if not origin_id:
|
| 267 |
origin_id = msg.message_id
|
|
@@ -279,7 +307,6 @@ class CoordinatorService:
|
|
| 279 |
|
| 280 |
if depth >= _MAX_MENTION_DEPTH:
|
| 281 |
if is_quant:
|
| 282 |
-
# Mid-chain quant checkpoint — pause and reset, don't hard-stop
|
| 283 |
templates = _build_input_templates(
|
| 284 |
"checkpoint", next_role=mention.mentioned_role
|
| 285 |
)
|
|
@@ -291,7 +318,7 @@ class CoordinatorService:
|
|
| 291 |
f"This is a natural human review point — check the quant artifacts before proceeding."
|
| 292 |
f"{templates}",
|
| 293 |
)
|
| 294 |
-
depth_dict[origin_id] = 0
|
| 295 |
else:
|
| 296 |
await self._post(
|
| 297 |
"coordinator",
|
|
@@ -354,19 +381,32 @@ class CoordinatorService:
|
|
| 354 |
return
|
| 355 |
|
| 356 |
if entry.is_human:
|
| 357 |
-
# Forward to the human via a highlighted thread message
|
| 358 |
templates = _build_input_templates("uncertainty", next_role=entry.role)
|
| 359 |
await self._post(
|
| 360 |
"coordinator",
|
| 361 |
f"📨 **Coordinator** → @human (holding role *{entry.role}*): {mention.content}"
|
| 362 |
f"{templates}",
|
| 363 |
)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 364 |
return
|
| 365 |
|
| 366 |
-
# V4.
|
| 367 |
-
entry.agent.files = FileWriter(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 368 |
|
| 369 |
-
# Cost estimation gate (NFR §5)
|
| 370 |
try:
|
| 371 |
await self._maybe_gate_cost(mention)
|
| 372 |
except _CostRejected:
|
|
@@ -409,42 +449,41 @@ class CoordinatorService:
|
|
| 409 |
await self._post(entry.role, response.content)
|
| 410 |
self.session.post(entry.role, response.content)
|
| 411 |
|
| 412 |
-
# V4.
|
| 413 |
-
|
| 414 |
-
|
|
|
|
|
|
|
| 415 |
if response.content.startswith("Skipped —"):
|
| 416 |
-
if response.mentions
|
| 417 |
-
|
| 418 |
-
|
| 419 |
-
|
| 420 |
-
|
| 421 |
-
|
| 422 |
-
|
|
|
|
|
|
|
| 423 |
return
|
| 424 |
|
| 425 |
-
#
|
| 426 |
-
|
| 427 |
-
|
| 428 |
-
|
| 429 |
-
|
| 430 |
-
|
| 431 |
-
|
| 432 |
-
|
| 433 |
-
|
| 434 |
-
|
| 435 |
-
|
| 436 |
-
|
| 437 |
-
|
| 438 |
-
|
| 439 |
-
|
| 440 |
-
|
| 441 |
-
|
| 442 |
-
|
| 443 |
-
await self.dispatch(
|
| 444 |
-
from_role=entry.role,
|
| 445 |
-
text=follow_up_text + " " + response.content[:200],
|
| 446 |
-
origin_id=origin_id,
|
| 447 |
-
)
|
| 448 |
|
| 449 |
async def _maybe_gate_cost(self, mention: Mention) -> None:
|
| 450 |
"""
|
|
@@ -490,6 +529,27 @@ class CoordinatorService:
|
|
| 490 |
manager = ResearchStateManager(self.session.session_dir)
|
| 491 |
current = manager.load()
|
| 492 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 493 |
papers_raw = response.metadata.get("papers", [])
|
| 494 |
if papers_raw:
|
| 495 |
papers = [
|
|
@@ -511,3 +571,146 @@ class CoordinatorService:
|
|
| 511 |
|
| 512 |
current.compress()
|
| 513 |
manager.save(current)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4 |
it parses @mentions, routes tasks to agents or the human, maintains the
|
| 5 |
Research State, fires checkpoint gates, and detects @mention loops.
|
| 6 |
|
| 7 |
+
V4.3: Routing now goes through the EventBus. The Coordinator publishes
|
| 8 |
+
``AgentCompletedEvent`` / ``AgentBlockedEvent`` / ``HumanInputRequiredEvent``
|
| 9 |
+
after each agent run and reacts to them via subscribed handlers. Depth
|
| 10 |
+
tracking has moved into ``on_agent_completed``.
|
| 11 |
+
|
| 12 |
This module also exposes the top-level ``CoordinatorService`` which drives an
|
| 13 |
entire session (CLI or Slack webhook).
|
| 14 |
"""
|
|
|
|
| 22 |
from typing import Any, Callable, Awaitable
|
| 23 |
|
| 24 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 25 |
+
from polyhedra.core.cache import SharedCache
|
| 26 |
+
from polyhedra.core.eventbus import (
|
| 27 |
+
EventBus, get_bus, clear_bus,
|
| 28 |
+
AgentCompletedEvent, AgentBlockedEvent,
|
| 29 |
+
HumanInputRequiredEvent, PortfolioAlertEvent,
|
| 30 |
+
)
|
| 31 |
from polyhedra.core.mention_parser import MentionParser
|
| 32 |
from polyhedra.core.research_state import ResearchStateManager, Paper, Gap, Decision, Hypothesis
|
| 33 |
from polyhedra.core.role_registry import RoleRegistry, RoleEntry, HELD_BY_AGENT, HELD_BY_HUMAN
|
| 34 |
from polyhedra.core.session import Session
|
| 35 |
from polyhedra.services.file_writer import FileWriter
|
| 36 |
from polyhedra.services.llm_service import LLMService
|
| 37 |
+
from polyhedra.services.rag_service import RAGService
|
| 38 |
|
| 39 |
logger = logging.getLogger(__name__)
|
| 40 |
|
|
|
|
| 262 |
self._mention_depth: dict[str, int] = {} # keyed by originating message_id
|
| 263 |
self._quant_mention_depth: dict[str, int] = {} # separate counter for quant chain
|
| 264 |
|
| 265 |
+
# V4.3 infrastructure
|
| 266 |
+
self._cache = SharedCache()
|
| 267 |
+
self._cache.warm_from_disk(session.session_dir)
|
| 268 |
+
self._rag = RAGService(session.session_dir)
|
| 269 |
+
self._rag.rebuild_artifact_index_from_disk(session.session_dir)
|
| 270 |
+
self._bus = get_bus(session.session_id)
|
| 271 |
+
self._bus.subscribe(AgentCompletedEvent, self._on_agent_completed)
|
| 272 |
+
self._bus.subscribe(AgentBlockedEvent, self._on_agent_blocked)
|
| 273 |
+
self._bus.subscribe(HumanInputRequiredEvent, self._on_human_input_required)
|
| 274 |
+
self._bus.subscribe(PortfolioAlertEvent, self._on_portfolio_alert)
|
| 275 |
+
|
| 276 |
# ------------------------------------------------------------------ #
|
| 277 |
# Public API
|
| 278 |
# ------------------------------------------------------------------ #
|
|
|
|
| 281 |
"""
|
| 282 |
Entry point for every incoming message.
|
| 283 |
|
| 284 |
+
Handles /poly slash commands first, then parses @mentions and routes.
|
|
|
|
|
|
|
| 285 |
"""
|
| 286 |
+
# V4.3: handle /poly commands before mention parsing
|
| 287 |
+
stripped = text.strip()
|
| 288 |
+
if stripped.startswith("/poly "):
|
| 289 |
+
handled = await self._handle_slash_command(stripped)
|
| 290 |
+
if handled:
|
| 291 |
+
return
|
| 292 |
+
|
| 293 |
msg = self.session.post(from_role=from_role, content=text)
|
| 294 |
if not origin_id:
|
| 295 |
origin_id = msg.message_id
|
|
|
|
| 307 |
|
| 308 |
if depth >= _MAX_MENTION_DEPTH:
|
| 309 |
if is_quant:
|
|
|
|
| 310 |
templates = _build_input_templates(
|
| 311 |
"checkpoint", next_role=mention.mentioned_role
|
| 312 |
)
|
|
|
|
| 318 |
f"This is a natural human review point — check the quant artifacts before proceeding."
|
| 319 |
f"{templates}",
|
| 320 |
)
|
| 321 |
+
depth_dict[origin_id] = 0
|
| 322 |
else:
|
| 323 |
await self._post(
|
| 324 |
"coordinator",
|
|
|
|
| 381 |
return
|
| 382 |
|
| 383 |
if entry.is_human:
|
|
|
|
| 384 |
templates = _build_input_templates("uncertainty", next_role=entry.role)
|
| 385 |
await self._post(
|
| 386 |
"coordinator",
|
| 387 |
f"📨 **Coordinator** → @human (holding role *{entry.role}*): {mention.content}"
|
| 388 |
f"{templates}",
|
| 389 |
)
|
| 390 |
+
# Publish HumanInputRequiredEvent (FR-2.x)
|
| 391 |
+
self._bus.publish(HumanInputRequiredEvent(
|
| 392 |
+
session_id=self.session.session_id,
|
| 393 |
+
agent_role=entry.role,
|
| 394 |
+
question=mention.content,
|
| 395 |
+
content=f"Human input required for role *{entry.role}*",
|
| 396 |
+
))
|
| 397 |
return
|
| 398 |
|
| 399 |
+
# V4.3: inject FileWriter with SharedCache + RAGService (FR-1.1 – FR-3.1)
|
| 400 |
+
entry.agent.files = FileWriter(
|
| 401 |
+
self.session.session_dir,
|
| 402 |
+
session_id=self.session.session_id,
|
| 403 |
+
cache=self._cache,
|
| 404 |
+
rag=self._rag,
|
| 405 |
+
)
|
| 406 |
+
# V4.3: inject EventBus and TokenBudget into agent
|
| 407 |
+
entry.agent.bus = self._bus
|
| 408 |
|
| 409 |
+
# Cost estimation gate (NFR §5)
|
| 410 |
try:
|
| 411 |
await self._maybe_gate_cost(mention)
|
| 412 |
except _CostRejected:
|
|
|
|
| 449 |
await self._post(entry.role, response.content)
|
| 450 |
self.session.post(entry.role, response.content)
|
| 451 |
|
| 452 |
+
# V4.3: determine current depth for the event
|
| 453 |
+
is_quant = mention.mentioned_role in _QUANT_ROLES
|
| 454 |
+
current_depth = (self._quant_mention_depth if is_quant else self._mention_depth).get(origin_id, 0)
|
| 455 |
+
|
| 456 |
+
# V4.3: detect blocked state → publish AgentBlockedEvent
|
| 457 |
if response.content.startswith("Skipped —"):
|
| 458 |
+
blocked_role = response.mentions[0] if response.mentions else None
|
| 459 |
+
self._bus.publish(AgentBlockedEvent(
|
| 460 |
+
session_id=self.session.session_id,
|
| 461 |
+
agent_role=entry.role,
|
| 462 |
+
reason=response.content[:200],
|
| 463 |
+
missing_artifact=response.artifact_path,
|
| 464 |
+
suggested_role=blocked_role,
|
| 465 |
+
content=response.content,
|
| 466 |
+
))
|
| 467 |
return
|
| 468 |
|
| 469 |
+
# V4.3: publish AgentCompletedEvent — Coordinator's on_agent_completed
|
| 470 |
+
# handles state updates, checkpoint, and chaining (FR-2.1 / FR-2.3)
|
| 471 |
+
next_role = response.mentions[0] if response.mentions else None
|
| 472 |
+
event = AgentCompletedEvent(
|
| 473 |
+
session_id=self.session.session_id,
|
| 474 |
+
agent_role=entry.role,
|
| 475 |
+
artifact_path=response.artifact_path,
|
| 476 |
+
next_role=next_role,
|
| 477 |
+
reason="",
|
| 478 |
+
depth=current_depth,
|
| 479 |
+
content=response.content,
|
| 480 |
+
updates_state=response.updates_state,
|
| 481 |
+
state_patch=response.state_patch,
|
| 482 |
+
checkpoint_required=response.checkpoint_required,
|
| 483 |
+
checkpoint_summary=response.checkpoint_summary,
|
| 484 |
+
origin_id=origin_id,
|
| 485 |
+
)
|
| 486 |
+
self._bus.publish(event)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 487 |
|
| 488 |
async def _maybe_gate_cost(self, mention: Mention) -> None:
|
| 489 |
"""
|
|
|
|
| 529 |
manager = ResearchStateManager(self.session.session_dir)
|
| 530 |
current = manager.load()
|
| 531 |
|
| 532 |
+
papers_raw = response.metadata.get("papers", [])
|
| 533 |
+
if papers_raw:
|
| 534 |
+
papers = [
|
| 535 |
+
Paper(
|
| 536 |
+
title=p.get("title", "Unknown"),
|
| 537 |
+
paper_id=p.get("paperId", "") or p.get("paper_id", ""),
|
| 538 |
+
year=p.get("year"),
|
| 539 |
+
relevance_score=float(p.get("relevanceScore") or p.get("citationCount") or 0),
|
| 540 |
+
one_line_summary=(p.get("abstract") or "")[:100],
|
| 541 |
+
bibtex_key=(p.get("title", "").split()[0].lower() if p.get("title") else ""),
|
| 542 |
+
)
|
| 543 |
+
for p in papers_raw
|
| 544 |
+
]
|
| 545 |
+
current.key_papers = papers
|
| 546 |
+
|
| 547 |
+
pending_task = response.metadata.get("pending_task")
|
| 548 |
+
if pending_task and pending_task not in current.pending_tasks:
|
| 549 |
+
current.pending_tasks.append(pending_task)
|
| 550 |
+
|
| 551 |
+
current = manager.load()
|
| 552 |
+
|
| 553 |
papers_raw = response.metadata.get("papers", [])
|
| 554 |
if papers_raw:
|
| 555 |
papers = [
|
|
|
|
| 571 |
|
| 572 |
current.compress()
|
| 573 |
manager.save(current)
|
| 574 |
+
|
| 575 |
+
# ------------------------------------------------------------------ #
|
| 576 |
+
# V4.3 EventBus handlers (FR-2.x)
|
| 577 |
+
# ------------------------------------------------------------------ #
|
| 578 |
+
|
| 579 |
+
async def _on_agent_completed(self, event: AgentCompletedEvent) -> None:
|
| 580 |
+
"""
|
| 581 |
+
React to an agent completing — state update, checkpoint, chain to next.
|
| 582 |
+
Depth tracking lives here (FR-2.3). EventBus schedules this as a task.
|
| 583 |
+
"""
|
| 584 |
+
# State update
|
| 585 |
+
if event.updates_state and event.state_patch:
|
| 586 |
+
manager = ResearchStateManager(self.session.session_dir)
|
| 587 |
+
current = manager.load()
|
| 588 |
+
for key, value in event.state_patch.items():
|
| 589 |
+
if hasattr(current, key):
|
| 590 |
+
setattr(current, key, value)
|
| 591 |
+
current.compress()
|
| 592 |
+
manager.save(current)
|
| 593 |
+
|
| 594 |
+
# Checkpoint gate
|
| 595 |
+
if event.checkpoint_required:
|
| 596 |
+
result = await self._checkpoint(event.checkpoint_summary)
|
| 597 |
+
if not result.approved:
|
| 598 |
+
await self._post(
|
| 599 |
+
"coordinator",
|
| 600 |
+
"⏸ **Coordinator** — session paused at user's request. "
|
| 601 |
+
"Resume anytime with `/poly resume` or by continuing in the thread.",
|
| 602 |
+
)
|
| 603 |
+
return
|
| 604 |
+
|
| 605 |
+
# Async flush cache to disk (FR-1.2)
|
| 606 |
+
await self._cache.async_flush_to_disk(self.session.session_dir)
|
| 607 |
+
|
| 608 |
+
# Chain to next agent
|
| 609 |
+
if event.next_role:
|
| 610 |
+
follow_up = Mention(
|
| 611 |
+
mentioned_role=event.next_role,
|
| 612 |
+
from_role=event.agent_role,
|
| 613 |
+
content=f"continue — previous: {event.content[:200]}",
|
| 614 |
+
)
|
| 615 |
+
await self._route(follow_up, event.origin_id)
|
| 616 |
+
|
| 617 |
+
async def _on_agent_blocked(self, event: AgentBlockedEvent) -> None:
|
| 618 |
+
"""React to an agent blocked on missing data (FR-2.x)."""
|
| 619 |
+
templates = _build_input_templates("agent_blocked", next_role=event.suggested_role)
|
| 620 |
+
await self._post(
|
| 621 |
+
"coordinator",
|
| 622 |
+
f"⚠️ **Coordinator** — @{event.agent_role} is blocked: {event.reason}"
|
| 623 |
+
f"{templates}",
|
| 624 |
+
)
|
| 625 |
+
if event.suggested_role:
|
| 626 |
+
follow_up = Mention(
|
| 627 |
+
mentioned_role=event.suggested_role,
|
| 628 |
+
from_role=event.agent_role,
|
| 629 |
+
content=f"provide missing data: {event.missing_artifact or 'unknown artifact'}",
|
| 630 |
+
)
|
| 631 |
+
await self._route(follow_up, "")
|
| 632 |
+
|
| 633 |
+
async def _on_human_input_required(self, event: HumanInputRequiredEvent) -> None:
|
| 634 |
+
"""React to an agent requesting human input. Already posted — no-op."""
|
| 635 |
+
|
| 636 |
+
async def _on_portfolio_alert(self, event: PortfolioAlertEvent) -> None:
|
| 637 |
+
"""React to a portfolio threshold breach (FR-2.4) — independent of running chain."""
|
| 638 |
+
await self._post("portfoliomonitor", event.content)
|
| 639 |
+
|
| 640 |
+
# ------------------------------------------------------------------ #
|
| 641 |
+
# V4.3 slash command handler
|
| 642 |
+
# ------------------------------------------------------------------ #
|
| 643 |
+
|
| 644 |
+
async def _handle_slash_command(self, text: str) -> bool:
|
| 645 |
+
"""
|
| 646 |
+
Handle /poly V4.3 commands. Returns True if the command was consumed.
|
| 647 |
+
|
| 648 |
+
New in V4.3:
|
| 649 |
+
/poly cache clear — flush session cache, reload from disk on next access
|
| 650 |
+
/poly cache status — show hit/miss stats
|
| 651 |
+
/poly tokens — show session token usage by agent
|
| 652 |
+
"""
|
| 653 |
+
parts = text.strip().split()
|
| 654 |
+
if len(parts) < 2 or parts[0] != "/poly":
|
| 655 |
+
return False
|
| 656 |
+
|
| 657 |
+
sub = parts[1].lower()
|
| 658 |
+
|
| 659 |
+
if sub == "cache" and len(parts) >= 3:
|
| 660 |
+
action = parts[2].lower()
|
| 661 |
+
if action == "clear":
|
| 662 |
+
self._cache.clear()
|
| 663 |
+
await self._post(
|
| 664 |
+
"coordinator",
|
| 665 |
+
"✅ **Coordinator** — session cache cleared. "
|
| 666 |
+
"Next artifact read will reload from disk.",
|
| 667 |
+
)
|
| 668 |
+
return True
|
| 669 |
+
if action == "status":
|
| 670 |
+
stats = self._cache.stats.to_dict()
|
| 671 |
+
entry_count = len(self._cache._store)
|
| 672 |
+
await self._post(
|
| 673 |
+
"coordinator",
|
| 674 |
+
f"📊 **Cache status**\n\n"
|
| 675 |
+
f"- Entries in memory: {entry_count}\n"
|
| 676 |
+
f"- Hits: {stats['hits']} / Misses: {stats['misses']}\n"
|
| 677 |
+
f"- Hit rate: {stats['hit_rate_pct']}%",
|
| 678 |
+
)
|
| 679 |
+
return True
|
| 680 |
+
|
| 681 |
+
if sub == "tokens":
|
| 682 |
+
await self._post_token_summary()
|
| 683 |
+
return True
|
| 684 |
+
|
| 685 |
+
return False
|
| 686 |
+
|
| 687 |
+
async def _post_token_summary(self) -> None:
|
| 688 |
+
"""Post session token usage summary (FR-4.5 /poly tokens)."""
|
| 689 |
+
state = self.session.research_state
|
| 690 |
+
qs = state.quant_state if state else None
|
| 691 |
+
if not qs or not qs.token_log:
|
| 692 |
+
await self._post("coordinator", "📊 **Token usage** — no token records for this session yet.")
|
| 693 |
+
return
|
| 694 |
+
|
| 695 |
+
by_agent: dict[str, dict] = {}
|
| 696 |
+
for entry in qs.token_log:
|
| 697 |
+
rec = by_agent.setdefault(entry.agent_role, {
|
| 698 |
+
"prompt": 0, "completion": 0, "cost": 0.0, "cached": 0,
|
| 699 |
+
})
|
| 700 |
+
rec["prompt"] += entry.prompt_tokens
|
| 701 |
+
rec["completion"] += entry.completion_tokens
|
| 702 |
+
rec["cost"] += entry.estimated_cost_usd
|
| 703 |
+
if entry.cache_hit:
|
| 704 |
+
rec["cached"] += 1
|
| 705 |
+
|
| 706 |
+
total_cost = sum(r["cost"] for r in by_agent.values())
|
| 707 |
+
lines = [f"📊 **Token usage — session {self.session.session_id[:8]}**\n"]
|
| 708 |
+
lines.append("| Agent | Prompt | Completion | Est. cost | Cache hits |")
|
| 709 |
+
lines.append("|---|---|---|---|---|")
|
| 710 |
+
for role, rec in sorted(by_agent.items()):
|
| 711 |
+
lines.append(
|
| 712 |
+
f"| `{role}` | {rec['prompt']:,} | {rec['completion']:,} "
|
| 713 |
+
f"| ${rec['cost']:.4f} | {rec['cached']} |"
|
| 714 |
+
)
|
| 715 |
+
lines.append(f"\n**Total estimated cost:** ${total_cost:.4f}")
|
| 716 |
+
await self._post("coordinator", "\n".join(lines))
|
|
@@ -15,6 +15,7 @@ from typing import Any
|
|
| 15 |
|
| 16 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 17 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 18 |
from polyhedra.services.llm_service import LLMService
|
| 19 |
|
| 20 |
logger = logging.getLogger(__name__)
|
|
@@ -36,6 +37,7 @@ class BacktesterAgent(Agent):
|
|
| 36 |
f"Flag signals with fewer than {_MIN_TRADES_THRESHOLD} occurrences as statistically weak. "
|
| 37 |
"Do NOT recommend which signals to use — report metrics only."
|
| 38 |
)
|
|
|
|
| 39 |
|
| 40 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 41 |
super().__init__()
|
|
@@ -78,13 +80,18 @@ class BacktesterAgent(Agent):
|
|
| 78 |
|
| 79 |
try:
|
| 80 |
result = await self._llm.complete(prompt)
|
| 81 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 82 |
except Exception as exc:
|
| 83 |
logger.error("Backtester LLM call failed: %s", exc)
|
| 84 |
llm_text = (
|
| 85 |
"Backtest simulation could not be completed (LLM unavailable).\n"
|
| 86 |
'{"next": "riskanalyst", "reason": "Fallback — proceeding."}'
|
| 87 |
)
|
|
|
|
| 88 |
|
| 89 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 90 |
|
|
|
|
| 15 |
|
| 16 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 17 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 18 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 19 |
from polyhedra.services.llm_service import LLMService
|
| 20 |
|
| 21 |
logger = logging.getLogger(__name__)
|
|
|
|
| 37 |
f"Flag signals with fewer than {_MIN_TRADES_THRESHOLD} occurrences as statistically weak. "
|
| 38 |
"Do NOT recommend which signals to use — report metrics only."
|
| 39 |
)
|
| 40 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 41 |
|
| 42 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 43 |
super().__init__()
|
|
|
|
| 80 |
|
| 81 |
try:
|
| 82 |
result = await self._llm.complete(prompt)
|
| 83 |
+
if isinstance(result, tuple):
|
| 84 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 85 |
+
else:
|
| 86 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 87 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 88 |
except Exception as exc:
|
| 89 |
logger.error("Backtester LLM call failed: %s", exc)
|
| 90 |
llm_text = (
|
| 91 |
"Backtest simulation could not be completed (LLM unavailable).\n"
|
| 92 |
'{"next": "riskanalyst", "reason": "Fallback — proceeding."}'
|
| 93 |
)
|
| 94 |
+
prompt_tokens, completion_tokens = 0, 0
|
| 95 |
|
| 96 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 97 |
|
|
@@ -26,6 +26,8 @@ from datetime import date, datetime, timezone
|
|
| 26 |
from typing import Any
|
| 27 |
|
| 28 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
|
|
|
|
|
|
| 29 |
from polyhedra.services.llm_service import LLMService
|
| 30 |
|
| 31 |
logger = logging.getLogger(__name__)
|
|
@@ -80,6 +82,7 @@ class PortfolioMonitorAgent(Agent):
|
|
| 80 |
"and alert the human so they can make an informed decision. "
|
| 81 |
"You NEVER close positions — the human decides."
|
| 82 |
)
|
|
|
|
| 83 |
|
| 84 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 85 |
super().__init__()
|
|
@@ -212,6 +215,35 @@ class PortfolioMonitorAgent(Agent):
|
|
| 212 |
# Write daily log (FR-3.6)
|
| 213 |
self._write_daily_log(today, content, alerts)
|
| 214 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 215 |
# Update last_monitor_run in state
|
| 216 |
return AgentResponse(
|
| 217 |
agent_role=self.role,
|
|
|
|
| 26 |
from typing import Any
|
| 27 |
|
| 28 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 29 |
+
from polyhedra.core.eventbus import PortfolioAlertEvent
|
| 30 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 31 |
from polyhedra.services.llm_service import LLMService
|
| 32 |
|
| 33 |
logger = logging.getLogger(__name__)
|
|
|
|
| 82 |
"and alert the human so they can make an informed decision. "
|
| 83 |
"You NEVER close positions — the human decides."
|
| 84 |
)
|
| 85 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 86 |
|
| 87 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 88 |
super().__init__()
|
|
|
|
| 215 |
# Write daily log (FR-3.6)
|
| 216 |
self._write_daily_log(today, content, alerts)
|
| 217 |
|
| 218 |
+
# Emit PortfolioAlertEvent for each breach via EventBus (V4.3)
|
| 219 |
+
if alerts and self.bus is not None:
|
| 220 |
+
session_id = (
|
| 221 |
+
research_state.get("session", {}).get("session_id", "")
|
| 222 |
+
if isinstance(research_state.get("session"), dict)
|
| 223 |
+
else ""
|
| 224 |
+
)
|
| 225 |
+
for alert in alerts:
|
| 226 |
+
for breach in alert.get("breaches", []):
|
| 227 |
+
# Derive alert_type from breach text
|
| 228 |
+
if "take-profit" in breach.lower() or "take_profit" in breach.lower():
|
| 229 |
+
alert_type = "take_profit"
|
| 230 |
+
threshold = float(alert.get("tp", 0) or 0)
|
| 231 |
+
elif "stop-loss" in breach.lower() or "stop_loss" in breach.lower():
|
| 232 |
+
alert_type = "stop_loss"
|
| 233 |
+
threshold = float(alert.get("sl", 0) or 0)
|
| 234 |
+
else:
|
| 235 |
+
alert_type = "pct_move"
|
| 236 |
+
threshold = self._alert_move_pct
|
| 237 |
+
self.bus.publish(PortfolioAlertEvent(
|
| 238 |
+
session_id=session_id,
|
| 239 |
+
position_id=str(alert.get("position_id", alert.get("ticker", "?"))),
|
| 240 |
+
ticker=str(alert.get("ticker", "?")),
|
| 241 |
+
alert_type=alert_type,
|
| 242 |
+
current_price=float(alert.get("current", 0)),
|
| 243 |
+
threshold=threshold,
|
| 244 |
+
content=breach,
|
| 245 |
+
))
|
| 246 |
+
|
| 247 |
# Update last_monitor_run in state
|
| 248 |
return AgentResponse(
|
| 249 |
agent_role=self.role,
|
|
@@ -14,6 +14,7 @@ from typing import Any
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 17 |
from polyhedra.services.llm_service import LLMService
|
| 18 |
|
| 19 |
logger = logging.getLogger(__name__)
|
|
@@ -34,6 +35,7 @@ class QuantResearcherAgent(Agent):
|
|
| 34 |
"State your confidence (high/medium/speculative) and what would falsify each hypothesis. "
|
| 35 |
"Do NOT backtest signals yourself and do NOT make portfolio allocation decisions."
|
| 36 |
)
|
|
|
|
| 37 |
|
| 38 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 39 |
super().__init__()
|
|
@@ -77,13 +79,18 @@ class QuantResearcherAgent(Agent):
|
|
| 77 |
|
| 78 |
try:
|
| 79 |
result = await self._llm.complete(prompt)
|
| 80 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 81 |
except Exception as exc:
|
| 82 |
logger.error("QuantResearcher LLM call failed: %s", exc)
|
| 83 |
llm_text = (
|
| 84 |
"Signal discovery could not be completed (LLM unavailable).\n"
|
| 85 |
-
'{"next": "backtester", "reason": "Fallback
|
| 86 |
)
|
|
|
|
| 87 |
|
| 88 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 89 |
|
|
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 17 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 18 |
from polyhedra.services.llm_service import LLMService
|
| 19 |
|
| 20 |
logger = logging.getLogger(__name__)
|
|
|
|
| 35 |
"State your confidence (high/medium/speculative) and what would falsify each hypothesis. "
|
| 36 |
"Do NOT backtest signals yourself and do NOT make portfolio allocation decisions."
|
| 37 |
)
|
| 38 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 39 |
|
| 40 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 41 |
super().__init__()
|
|
|
|
| 79 |
|
| 80 |
try:
|
| 81 |
result = await self._llm.complete(prompt)
|
| 82 |
+
if isinstance(result, tuple):
|
| 83 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 84 |
+
else:
|
| 85 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 86 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 87 |
except Exception as exc:
|
| 88 |
logger.error("QuantResearcher LLM call failed: %s", exc)
|
| 89 |
llm_text = (
|
| 90 |
"Signal discovery could not be completed (LLM unavailable).\n"
|
| 91 |
+
'{"next": "backtester", "reason": "Fallback \u2014 proceeding."}'
|
| 92 |
)
|
| 93 |
+
prompt_tokens, completion_tokens = 0, 0
|
| 94 |
|
| 95 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 96 |
|
|
@@ -20,6 +20,7 @@ from typing import Any
|
|
| 20 |
|
| 21 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 22 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 23 |
from polyhedra.services.llm_service import LLMService
|
| 24 |
|
| 25 |
logger = logging.getLogger(__name__)
|
|
@@ -42,6 +43,7 @@ class QuantStrategistAgent(Agent):
|
|
| 42 |
"Every proposal must include full rationale and a risk rating from RiskAnalyst. "
|
| 43 |
"You must ALWAYS route to @human — the human approves all paper trades."
|
| 44 |
)
|
|
|
|
| 45 |
|
| 46 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 47 |
super().__init__()
|
|
@@ -93,10 +95,15 @@ class QuantStrategistAgent(Agent):
|
|
| 93 |
|
| 94 |
try:
|
| 95 |
result = await self._llm.complete(prompt)
|
| 96 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 97 |
except Exception as exc:
|
| 98 |
logger.error("QuantStrategist LLM call failed: %s", exc)
|
| 99 |
llm_text = "Trade proposal generation could not be completed (LLM unavailable)."
|
|
|
|
| 100 |
|
| 101 |
# QuantStrategist always routes to human regardless of LLM routing decision
|
| 102 |
_, _, proposals = parse_llm_routing(llm_text)
|
|
|
|
| 20 |
|
| 21 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 22 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 23 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 24 |
from polyhedra.services.llm_service import LLMService
|
| 25 |
|
| 26 |
logger = logging.getLogger(__name__)
|
|
|
|
| 43 |
"Every proposal must include full rationale and a risk rating from RiskAnalyst. "
|
| 44 |
"You must ALWAYS route to @human — the human approves all paper trades."
|
| 45 |
)
|
| 46 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 47 |
|
| 48 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 49 |
super().__init__()
|
|
|
|
| 95 |
|
| 96 |
try:
|
| 97 |
result = await self._llm.complete(prompt)
|
| 98 |
+
if isinstance(result, tuple):
|
| 99 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 100 |
+
else:
|
| 101 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 102 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 103 |
except Exception as exc:
|
| 104 |
logger.error("QuantStrategist LLM call failed: %s", exc)
|
| 105 |
llm_text = "Trade proposal generation could not be completed (LLM unavailable)."
|
| 106 |
+
prompt_tokens, completion_tokens = 0, 0
|
| 107 |
|
| 108 |
# QuantStrategist always routes to human regardless of LLM routing decision
|
| 109 |
_, _, proposals = parse_llm_routing(llm_text)
|
|
@@ -14,6 +14,7 @@ from typing import Any
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 17 |
from polyhedra.services.llm_service import LLMService
|
| 18 |
|
| 19 |
logger = logging.getLogger(__name__)
|
|
@@ -33,6 +34,7 @@ class RiskAnalystAgent(Agent):
|
|
| 33 |
"Assign a risk verdict per signal: Acceptable / Elevated / Reject. "
|
| 34 |
"Do NOT make portfolio allocation decisions — provide risk ratings only."
|
| 35 |
)
|
|
|
|
| 36 |
|
| 37 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 38 |
super().__init__()
|
|
@@ -72,13 +74,18 @@ class RiskAnalystAgent(Agent):
|
|
| 72 |
|
| 73 |
try:
|
| 74 |
result = await self._llm.complete(prompt)
|
| 75 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 76 |
except Exception as exc:
|
| 77 |
logger.error("RiskAnalyst LLM call failed: %s", exc)
|
| 78 |
llm_text = (
|
| 79 |
"Risk assessment could not be completed (LLM unavailable).\n"
|
| 80 |
-
'{"next": "quantstrategist", "reason": "Fallback
|
| 81 |
)
|
|
|
|
| 82 |
|
| 83 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 84 |
|
|
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 17 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 18 |
from polyhedra.services.llm_service import LLMService
|
| 19 |
|
| 20 |
logger = logging.getLogger(__name__)
|
|
|
|
| 34 |
"Assign a risk verdict per signal: Acceptable / Elevated / Reject. "
|
| 35 |
"Do NOT make portfolio allocation decisions — provide risk ratings only."
|
| 36 |
)
|
| 37 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 38 |
|
| 39 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 40 |
super().__init__()
|
|
|
|
| 74 |
|
| 75 |
try:
|
| 76 |
result = await self._llm.complete(prompt)
|
| 77 |
+
if isinstance(result, tuple):
|
| 78 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 79 |
+
else:
|
| 80 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 81 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 82 |
except Exception as exc:
|
| 83 |
logger.error("RiskAnalyst LLM call failed: %s", exc)
|
| 84 |
llm_text = (
|
| 85 |
"Risk assessment could not be completed (LLM unavailable).\n"
|
| 86 |
+
'{"next": "quantstrategist", "reason": "Fallback \u2014 proceeding."}'
|
| 87 |
)
|
| 88 |
+
prompt_tokens, completion_tokens = 0, 0
|
| 89 |
|
| 90 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 91 |
|
|
@@ -14,6 +14,7 @@ from typing import Any
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 17 |
from polyhedra.services.llm_service import LLMService
|
| 18 |
|
| 19 |
logger = logging.getLogger(__name__)
|
|
@@ -56,6 +57,7 @@ class SentimentAnalystAgent(Agent):
|
|
| 56 |
"Do NOT make portfolio allocation decisions — score sentiment signals only. "
|
| 57 |
"Be precise: cite specific article themes, earnings figures, and sentiment scores."
|
| 58 |
)
|
|
|
|
| 59 |
|
| 60 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 61 |
super().__init__()
|
|
@@ -105,14 +107,19 @@ class SentimentAnalystAgent(Agent):
|
|
| 105 |
|
| 106 |
try:
|
| 107 |
result = await self._llm.complete(prompt)
|
| 108 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 109 |
except Exception as exc:
|
| 110 |
logger.error("SentimentAnalyst LLM call failed: %s", exc)
|
| 111 |
llm_text = (
|
| 112 |
f"Sentiment analysis could not be completed (LLM unavailable). "
|
| 113 |
f"Tickers: {', '.join(tickers)}.\n"
|
| 114 |
-
f'{{"next": "quantresearcher", "reason": "Fallback
|
| 115 |
)
|
|
|
|
| 116 |
|
| 117 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 118 |
|
|
|
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 17 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 18 |
from polyhedra.services.llm_service import LLMService
|
| 19 |
|
| 20 |
logger = logging.getLogger(__name__)
|
|
|
|
| 57 |
"Do NOT make portfolio allocation decisions — score sentiment signals only. "
|
| 58 |
"Be precise: cite specific article themes, earnings figures, and sentiment scores."
|
| 59 |
)
|
| 60 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 61 |
|
| 62 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 63 |
super().__init__()
|
|
|
|
| 107 |
|
| 108 |
try:
|
| 109 |
result = await self._llm.complete(prompt)
|
| 110 |
+
if isinstance(result, tuple):
|
| 111 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 112 |
+
else:
|
| 113 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 114 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 115 |
except Exception as exc:
|
| 116 |
logger.error("SentimentAnalyst LLM call failed: %s", exc)
|
| 117 |
llm_text = (
|
| 118 |
f"Sentiment analysis could not be completed (LLM unavailable). "
|
| 119 |
f"Tickers: {', '.join(tickers)}.\n"
|
| 120 |
+
f'{{"next": "quantresearcher", "reason": "Fallback \u2014 proceeding with available data."}}'
|
| 121 |
)
|
| 122 |
+
prompt_tokens, completion_tokens = 0, 0
|
| 123 |
|
| 124 |
next_role, reason, analysis = parse_llm_routing(llm_text)
|
| 125 |
|
|
@@ -1,4 +1,4 @@
|
|
| 1 |
-
"""TrendAnalystAgent — Technical Analyst for Polyhedra V4.
|
| 2 |
|
| 3 |
Reads raw data summaries written by DataFetcher and produces a technical
|
| 4 |
analysis document for each ticker. Does NOT make trading decisions.
|
|
@@ -9,11 +9,12 @@ DISCLAIMER: Paper trading simulation only. Educational purposes.
|
|
| 9 |
from __future__ import annotations
|
| 10 |
|
| 11 |
import logging
|
| 12 |
-
from datetime import date
|
| 13 |
from typing import Any
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 17 |
from polyhedra.services.llm_service import LLMService
|
| 18 |
|
| 19 |
logger = logging.getLogger(__name__)
|
|
@@ -40,6 +41,7 @@ class TrendAnalystAgent(Agent):
|
|
| 40 |
"Describe what the data shows — direction, magnitude, momentum, volume. "
|
| 41 |
"Be precise and data-driven. Reference specific indicator values."
|
| 42 |
)
|
|
|
|
| 43 |
|
| 44 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 45 |
super().__init__()
|
|
@@ -88,7 +90,11 @@ class TrendAnalystAgent(Agent):
|
|
| 88 |
|
| 89 |
try:
|
| 90 |
result = await self._llm.complete(prompt)
|
| 91 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 92 |
except Exception as exc:
|
| 93 |
logger.error("TrendAnalyst LLM call failed: %s", exc)
|
| 94 |
llm_text = (
|
|
|
|
| 1 |
+
"""TrendAnalystAgent — Technical Analyst for Polyhedra V4.3.
|
| 2 |
|
| 3 |
Reads raw data summaries written by DataFetcher and produces a technical
|
| 4 |
analysis document for each ticker. Does NOT make trading decisions.
|
|
|
|
| 9 |
from __future__ import annotations
|
| 10 |
|
| 11 |
import logging
|
| 12 |
+
from datetime import date, datetime, timezone
|
| 13 |
from typing import Any
|
| 14 |
|
| 15 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 16 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 17 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 18 |
from polyhedra.services.llm_service import LLMService
|
| 19 |
|
| 20 |
logger = logging.getLogger(__name__)
|
|
|
|
| 41 |
"Describe what the data shows — direction, magnitude, momentum, volume. "
|
| 42 |
"Be precise and data-driven. Reference specific indicator values."
|
| 43 |
)
|
| 44 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 45 |
|
| 46 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 47 |
super().__init__()
|
|
|
|
| 90 |
|
| 91 |
try:
|
| 92 |
result = await self._llm.complete(prompt)
|
| 93 |
+
if isinstance(result, tuple):
|
| 94 |
+
llm_text, prompt_tokens, completion_tokens = result
|
| 95 |
+
else:
|
| 96 |
+
llm_text, prompt_tokens, completion_tokens = result, 0, 0
|
| 97 |
+
self._log_token_usage(research_state, prompt_tokens, completion_tokens, cache_hit=False)
|
| 98 |
except Exception as exc:
|
| 99 |
logger.error("TrendAnalyst LLM call failed: %s", exc)
|
| 100 |
llm_text = (
|
|
@@ -22,6 +22,7 @@ from typing import Any
|
|
| 22 |
|
| 23 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 24 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
|
|
|
| 25 |
from polyhedra.services.llm_service import LLMService
|
| 26 |
|
| 27 |
logger = logging.getLogger(__name__)
|
|
@@ -53,6 +54,7 @@ class VizAgent(Agent):
|
|
| 53 |
"generate it, and write a concise 2-3 sentence caption explaining the key insight. "
|
| 54 |
"IMPORTANT: This is a paper trading simulation only. Not financial advice."
|
| 55 |
)
|
|
|
|
| 56 |
|
| 57 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 58 |
super().__init__()
|
|
@@ -426,7 +428,10 @@ class VizAgent(Agent):
|
|
| 426 |
)
|
| 427 |
try:
|
| 428 |
result = await self._llm.complete(prompt)
|
| 429 |
-
|
|
|
|
|
|
|
|
|
|
| 430 |
return text.strip()
|
| 431 |
except Exception:
|
| 432 |
return f"Chart generated for {subject} ({ct})."
|
|
|
|
| 22 |
|
| 23 |
from polyhedra.agents.base import Agent, AgentResponse, Mention
|
| 24 |
from polyhedra.agents.quant.routing import LLM_ROUTING_PROMPT, parse_llm_routing
|
| 25 |
+
from polyhedra.core.token_budget import TokenBudget
|
| 26 |
from polyhedra.services.llm_service import LLMService
|
| 27 |
|
| 28 |
logger = logging.getLogger(__name__)
|
|
|
|
| 54 |
"generate it, and write a concise 2-3 sentence caption explaining the key insight. "
|
| 55 |
"IMPORTANT: This is a paper trading simulation only. Not financial advice."
|
| 56 |
)
|
| 57 |
+
token_budget = TokenBudget(system=500, context=2000, task=500, thread=500, routing=200, total=4000)
|
| 58 |
|
| 59 |
def __init__(self, llm_service: LLMService | None = None) -> None:
|
| 60 |
super().__init__()
|
|
|
|
| 428 |
)
|
| 429 |
try:
|
| 430 |
result = await self._llm.complete(prompt)
|
| 431 |
+
if isinstance(result, tuple):
|
| 432 |
+
text = result[0] or ""
|
| 433 |
+
else:
|
| 434 |
+
text = result or ""
|
| 435 |
return text.strip()
|
| 436 |
except Exception:
|
| 437 |
return f"Chart generated for {subject} ({ct})."
|
|
@@ -324,6 +324,76 @@ def mcp() -> None:
|
|
| 324 |
_mcp_main()
|
| 325 |
|
| 326 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 327 |
# --------------------------------------------------------------------------- #
|
| 328 |
# Helpers
|
| 329 |
# --------------------------------------------------------------------------- #
|
|
|
|
| 324 |
_mcp_main()
|
| 325 |
|
| 326 |
|
| 327 |
+
@app.command()
|
| 328 |
+
def cache(
|
| 329 |
+
action: Annotated[str, typer.Argument(help='"clear" or "status"')],
|
| 330 |
+
session_id: Annotated[Optional[str], typer.Option("--session", "-s", help="Session ID (uses latest if omitted).")] = None,
|
| 331 |
+
) -> None:
|
| 332 |
+
"""Manage the session SharedCache.
|
| 333 |
+
|
| 334 |
+
\b
|
| 335 |
+
poly cache clear — flush all cached entries for the session
|
| 336 |
+
poly cache status — show cache stats (hit rate, entry count, size)
|
| 337 |
+
"""
|
| 338 |
+
if action not in ("clear", "status"):
|
| 339 |
+
err_console.print("[red]action must be 'clear' or 'status'[/red]")
|
| 340 |
+
raise typer.Exit(1)
|
| 341 |
+
|
| 342 |
+
sid = session_id or _latest_session_id()
|
| 343 |
+
if not sid:
|
| 344 |
+
err_console.print("[red]No sessions found. Start one with: poly init[/red]")
|
| 345 |
+
raise typer.Exit(1)
|
| 346 |
+
|
| 347 |
+
session = _sm.resume(sid)
|
| 348 |
+
if not session:
|
| 349 |
+
err_console.print(f"[red]Session {sid} not found.[/red]")
|
| 350 |
+
raise typer.Exit(1)
|
| 351 |
+
|
| 352 |
+
output_lines: list[str] = []
|
| 353 |
+
|
| 354 |
+
async def post_fn(from_role: str, content: str) -> None: # noqa: RUF029
|
| 355 |
+
output_lines.append(content)
|
| 356 |
+
|
| 357 |
+
async def checkpoint_fn(summary: str) -> CheckpointResult: # noqa: RUF029
|
| 358 |
+
return CheckpointResult(approved=True, response="yes")
|
| 359 |
+
|
| 360 |
+
service = CoordinatorService(session=session, post_fn=post_fn, checkpoint_fn=checkpoint_fn)
|
| 361 |
+
asyncio.run(service.dispatch(from_role="human", text=f"/poly cache {action}"))
|
| 362 |
+
|
| 363 |
+
for line in output_lines:
|
| 364 |
+
console.print(Markdown(line))
|
| 365 |
+
|
| 366 |
+
|
| 367 |
+
@app.command()
|
| 368 |
+
def tokens(
|
| 369 |
+
session_id: Annotated[Optional[str], typer.Argument(help="Session ID (uses latest if omitted).")] = None,
|
| 370 |
+
) -> None:
|
| 371 |
+
"""Print the token usage summary for a session."""
|
| 372 |
+
sid = session_id or _latest_session_id()
|
| 373 |
+
if not sid:
|
| 374 |
+
err_console.print("[red]No sessions found. Start one with: poly init[/red]")
|
| 375 |
+
raise typer.Exit(1)
|
| 376 |
+
|
| 377 |
+
session = _sm.resume(sid)
|
| 378 |
+
if not session:
|
| 379 |
+
err_console.print(f"[red]Session {sid} not found.[/red]")
|
| 380 |
+
raise typer.Exit(1)
|
| 381 |
+
|
| 382 |
+
output_lines: list[str] = []
|
| 383 |
+
|
| 384 |
+
async def post_fn(from_role: str, content: str) -> None: # noqa: RUF029
|
| 385 |
+
output_lines.append(content)
|
| 386 |
+
|
| 387 |
+
async def checkpoint_fn(summary: str) -> CheckpointResult: # noqa: RUF029
|
| 388 |
+
return CheckpointResult(approved=True, response="yes")
|
| 389 |
+
|
| 390 |
+
service = CoordinatorService(session=session, post_fn=post_fn, checkpoint_fn=checkpoint_fn)
|
| 391 |
+
asyncio.run(service.dispatch(from_role="human", text="/poly tokens"))
|
| 392 |
+
|
| 393 |
+
for line in output_lines:
|
| 394 |
+
console.print(Markdown(line))
|
| 395 |
+
|
| 396 |
+
|
| 397 |
# --------------------------------------------------------------------------- #
|
| 398 |
# Helpers
|
| 399 |
# --------------------------------------------------------------------------- #
|
|
@@ -1,14 +1,34 @@
|
|
| 1 |
-
"""Core package for Polyhedra
|
| 2 |
|
| 3 |
-
from polyhedra.core.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4 |
from polyhedra.core.role_registry import RoleEntry, RoleRegistry
|
| 5 |
from polyhedra.core.session import Session, SessionManager
|
|
|
|
| 6 |
|
| 7 |
__all__ = [
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 8 |
"ResearchState",
|
| 9 |
"ResearchStateManager",
|
| 10 |
"RoleEntry",
|
| 11 |
"RoleRegistry",
|
| 12 |
"Session",
|
| 13 |
"SessionManager",
|
|
|
|
|
|
|
|
|
|
|
|
|
| 14 |
]
|
|
|
|
| 1 |
+
"""Core package for Polyhedra v4.3."""
|
| 2 |
|
| 3 |
+
from polyhedra.core.cache import SharedCache
|
| 4 |
+
from polyhedra.core.eventbus import (
|
| 5 |
+
AgentBlockedEvent,
|
| 6 |
+
AgentCompletedEvent,
|
| 7 |
+
EventBus,
|
| 8 |
+
HumanInputRequiredEvent,
|
| 9 |
+
PortfolioAlertEvent,
|
| 10 |
+
get_bus,
|
| 11 |
+
)
|
| 12 |
+
from polyhedra.core.research_state import ResearchState, ResearchStateManager, TokenUsageEntry
|
| 13 |
from polyhedra.core.role_registry import RoleEntry, RoleRegistry
|
| 14 |
from polyhedra.core.session import Session, SessionManager
|
| 15 |
+
from polyhedra.core.token_budget import PromptBuilder, TokenBudget
|
| 16 |
|
| 17 |
__all__ = [
|
| 18 |
+
"AgentBlockedEvent",
|
| 19 |
+
"AgentCompletedEvent",
|
| 20 |
+
"EventBus",
|
| 21 |
+
"HumanInputRequiredEvent",
|
| 22 |
+
"PortfolioAlertEvent",
|
| 23 |
+
"PromptBuilder",
|
| 24 |
"ResearchState",
|
| 25 |
"ResearchStateManager",
|
| 26 |
"RoleEntry",
|
| 27 |
"RoleRegistry",
|
| 28 |
"Session",
|
| 29 |
"SessionManager",
|
| 30 |
+
"SharedCache",
|
| 31 |
+
"TokenBudget",
|
| 32 |
+
"TokenUsageEntry",
|
| 33 |
+
"get_bus",
|
| 34 |
]
|
|
@@ -0,0 +1,242 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""SharedCache — in-memory session cache for Polyhedra V4.3.
|
| 2 |
+
|
| 3 |
+
Replaces file-based shared state with a per-session in-memory layer.
|
| 4 |
+
The filesystem becomes a persistence backup only; agents never read
|
| 5 |
+
directly from disk during a live chain.
|
| 6 |
+
|
| 7 |
+
Cache key conventions:
|
| 8 |
+
state:<session_id> ResearchState / QuantState
|
| 9 |
+
artifact:<session_id>:<path> Artifact contents keyed by path
|
| 10 |
+
llm:<prompt_hash> LLM output keyed by prompt hash
|
| 11 |
+
api:<provider>:<endpoint>:<params> API response keyed by call signature
|
| 12 |
+
"""
|
| 13 |
+
|
| 14 |
+
from __future__ import annotations
|
| 15 |
+
|
| 16 |
+
import asyncio
|
| 17 |
+
import hashlib
|
| 18 |
+
import json
|
| 19 |
+
import logging
|
| 20 |
+
import time
|
| 21 |
+
from pathlib import Path
|
| 22 |
+
from typing import Any
|
| 23 |
+
|
| 24 |
+
logger = logging.getLogger(__name__)
|
| 25 |
+
|
| 26 |
+
# Per-prefix default TTLs (seconds) — overridden by env vars (see FR-1.4)
|
| 27 |
+
_DEFAULT_TTL: dict[str, int | None] = {
|
| 28 |
+
"state": None, # never expires mid-session
|
| 29 |
+
"artifact": None, # never expires mid-session
|
| 30 |
+
"llm": None, # never expires mid-session (FR-1.5)
|
| 31 |
+
"api:market": 86_400, # 24 h (FR-1.4)
|
| 32 |
+
"api:sentiment": 3_600, # 1 h (FR-1.4)
|
| 33 |
+
"api:quote": 60, # 1 min (FR-1.4)
|
| 34 |
+
}
|
| 35 |
+
|
| 36 |
+
|
| 37 |
+
def _pick_ttl(key: str) -> int | None:
|
| 38 |
+
"""Return the default TTL for a cache key based on its prefix."""
|
| 39 |
+
for prefix, ttl in _DEFAULT_TTL.items():
|
| 40 |
+
if key.startswith(prefix):
|
| 41 |
+
return ttl
|
| 42 |
+
return None
|
| 43 |
+
|
| 44 |
+
|
| 45 |
+
def prompt_hash(prompt: str) -> str:
|
| 46 |
+
"""Return a stable hex digest for a prompt string (used for llm:* keys)."""
|
| 47 |
+
return hashlib.sha256(prompt.encode()).hexdigest()[:16]
|
| 48 |
+
|
| 49 |
+
|
| 50 |
+
class _Entry:
|
| 51 |
+
__slots__ = ("value", "expires_at")
|
| 52 |
+
|
| 53 |
+
def __init__(self, value: Any, ttl: int | None) -> None:
|
| 54 |
+
self.value = value
|
| 55 |
+
self.expires_at: float | None = (time.monotonic() + ttl) if ttl is not None else None
|
| 56 |
+
|
| 57 |
+
def is_expired(self) -> bool:
|
| 58 |
+
if self.expires_at is None:
|
| 59 |
+
return False
|
| 60 |
+
return time.monotonic() > self.expires_at
|
| 61 |
+
|
| 62 |
+
|
| 63 |
+
class CacheStats:
|
| 64 |
+
"""Hit / miss counters for the current session (FR-1.8 /poly cache status)."""
|
| 65 |
+
|
| 66 |
+
def __init__(self) -> None:
|
| 67 |
+
self.hits = 0
|
| 68 |
+
self.misses = 0
|
| 69 |
+
|
| 70 |
+
@property
|
| 71 |
+
def total(self) -> int:
|
| 72 |
+
return self.hits + self.misses
|
| 73 |
+
|
| 74 |
+
@property
|
| 75 |
+
def hit_rate(self) -> float:
|
| 76 |
+
return self.hits / self.total if self.total else 0.0
|
| 77 |
+
|
| 78 |
+
def record_hit(self) -> None:
|
| 79 |
+
self.hits += 1
|
| 80 |
+
|
| 81 |
+
def record_miss(self) -> None:
|
| 82 |
+
self.misses += 1
|
| 83 |
+
|
| 84 |
+
def to_dict(self) -> dict[str, Any]:
|
| 85 |
+
return {
|
| 86 |
+
"hits": self.hits,
|
| 87 |
+
"misses": self.misses,
|
| 88 |
+
"total": self.total,
|
| 89 |
+
"hit_rate_pct": round(self.hit_rate * 100, 1),
|
| 90 |
+
}
|
| 91 |
+
|
| 92 |
+
|
| 93 |
+
class SharedCache:
|
| 94 |
+
"""
|
| 95 |
+
Per-session in-memory cache.
|
| 96 |
+
|
| 97 |
+
All agent reads go through the cache. FileWriter keeps cache and disk
|
| 98 |
+
in sync — this object is never written to directly by agents.
|
| 99 |
+
|
| 100 |
+
Scope: per-process, per-session. Not shared across sessions.
|
| 101 |
+
"""
|
| 102 |
+
|
| 103 |
+
def __init__(self) -> None:
|
| 104 |
+
self._store: dict[str, _Entry] = {}
|
| 105 |
+
self.stats = CacheStats()
|
| 106 |
+
|
| 107 |
+
# ------------------------------------------------------------------ #
|
| 108 |
+
# Core API (FR-1.1 – FR-1.7)
|
| 109 |
+
# ------------------------------------------------------------------ #
|
| 110 |
+
|
| 111 |
+
def get(self, key: str) -> Any | None:
|
| 112 |
+
"""Return cached value or None on miss / expiry."""
|
| 113 |
+
entry = self._store.get(key)
|
| 114 |
+
if entry is None:
|
| 115 |
+
self.stats.record_miss()
|
| 116 |
+
return None
|
| 117 |
+
if entry.is_expired():
|
| 118 |
+
del self._store[key]
|
| 119 |
+
self.stats.record_miss()
|
| 120 |
+
return None
|
| 121 |
+
self.stats.record_hit()
|
| 122 |
+
return entry.value
|
| 123 |
+
|
| 124 |
+
def set(self, key: str, value: Any, ttl: int | None = _SENTINEL := object()) -> None:
|
| 125 |
+
"""
|
| 126 |
+
Store a value under *key*.
|
| 127 |
+
|
| 128 |
+
If *ttl* is omitted the default for the key's prefix is used.
|
| 129 |
+
Pass ``ttl=None`` explicitly to store without expiry.
|
| 130 |
+
"""
|
| 131 |
+
resolved_ttl: int | None
|
| 132 |
+
if ttl is self._SENTINEL:
|
| 133 |
+
resolved_ttl = _pick_ttl(key)
|
| 134 |
+
else:
|
| 135 |
+
resolved_ttl = ttl # type: ignore[assignment]
|
| 136 |
+
self._store[key] = _Entry(value, resolved_ttl)
|
| 137 |
+
|
| 138 |
+
def invalidate(self, key: str) -> None:
|
| 139 |
+
"""Remove a single key."""
|
| 140 |
+
self._store.pop(key, None)
|
| 141 |
+
|
| 142 |
+
def invalidate_prefix(self, prefix: str) -> None:
|
| 143 |
+
"""Remove all keys whose name starts with *prefix* (FR-1.6)."""
|
| 144 |
+
victims = [k for k in self._store if k.startswith(prefix)]
|
| 145 |
+
for k in victims:
|
| 146 |
+
del self._store[k]
|
| 147 |
+
if victims:
|
| 148 |
+
logger.debug("SharedCache: invalidated %d keys with prefix %r", len(victims), prefix)
|
| 149 |
+
|
| 150 |
+
def clear(self) -> None:
|
| 151 |
+
"""Flush the entire in-memory cache (FR-1.8 /poly cache clear)."""
|
| 152 |
+
self._store.clear()
|
| 153 |
+
logger.info("SharedCache: flushed all entries")
|
| 154 |
+
|
| 155 |
+
# ------------------------------------------------------------------ #
|
| 156 |
+
# Persistence helpers (FR-1.9)
|
| 157 |
+
# ------------------------------------------------------------------ #
|
| 158 |
+
|
| 159 |
+
def flush_to_disk(self, session_dir: str | Path) -> None:
|
| 160 |
+
"""
|
| 161 |
+
Persist serialisable cache entries to ``<session_dir>/.cache_snapshot.json``.
|
| 162 |
+
|
| 163 |
+
Called by the Coordinator at session end or on explicit flush.
|
| 164 |
+
Non-serialisable entries (e.g. numpy arrays) are silently skipped.
|
| 165 |
+
"""
|
| 166 |
+
base = Path(session_dir)
|
| 167 |
+
snapshot: dict[str, Any] = {}
|
| 168 |
+
for key, entry in self._store.items():
|
| 169 |
+
if entry.is_expired():
|
| 170 |
+
continue
|
| 171 |
+
try:
|
| 172 |
+
json.dumps(entry.value) # serialisability check
|
| 173 |
+
snapshot[key] = {
|
| 174 |
+
"value": entry.value,
|
| 175 |
+
"expires_at": entry.expires_at,
|
| 176 |
+
}
|
| 177 |
+
except (TypeError, ValueError):
|
| 178 |
+
pass # skip non-serialisable (numpy arrays, etc.)
|
| 179 |
+
|
| 180 |
+
out = base / ".cache_snapshot.json"
|
| 181 |
+
out.parent.mkdir(parents=True, exist_ok=True)
|
| 182 |
+
try:
|
| 183 |
+
out.write_text(json.dumps(snapshot, indent=2), encoding="utf-8")
|
| 184 |
+
logger.debug("SharedCache: flushed %d entries to %s", len(snapshot), out)
|
| 185 |
+
except Exception as exc:
|
| 186 |
+
logger.warning("SharedCache.flush_to_disk failed: %s", exc)
|
| 187 |
+
|
| 188 |
+
def warm_from_disk(self, session_dir: str | Path) -> None:
|
| 189 |
+
"""
|
| 190 |
+
Restore cache from a disk snapshot (cold-start recovery, FR-1.9).
|
| 191 |
+
|
| 192 |
+
Only entries that have not yet expired are loaded.
|
| 193 |
+
"""
|
| 194 |
+
snapshot_path = Path(session_dir) / ".cache_snapshot.json"
|
| 195 |
+
if not snapshot_path.exists():
|
| 196 |
+
return
|
| 197 |
+
try:
|
| 198 |
+
raw = json.loads(snapshot_path.read_text(encoding="utf-8"))
|
| 199 |
+
except Exception as exc:
|
| 200 |
+
logger.warning("SharedCache.warm_from_disk failed to parse snapshot: %s", exc)
|
| 201 |
+
return
|
| 202 |
+
|
| 203 |
+
now = time.monotonic()
|
| 204 |
+
loaded = 0
|
| 205 |
+
for key, data in raw.items():
|
| 206 |
+
expires_at: float | None = data.get("expires_at")
|
| 207 |
+
if expires_at is not None and now > expires_at:
|
| 208 |
+
continue # skip expired
|
| 209 |
+
entry = _Entry.__new__(_Entry)
|
| 210 |
+
entry.value = data["value"]
|
| 211 |
+
entry.expires_at = expires_at
|
| 212 |
+
self._store[key] = entry
|
| 213 |
+
loaded += 1
|
| 214 |
+
|
| 215 |
+
logger.debug("SharedCache: warmed %d entries from %s", loaded, snapshot_path)
|
| 216 |
+
|
| 217 |
+
# ------------------------------------------------------------------ #
|
| 218 |
+
# Convenience: async flush (for Coordinator background use)
|
| 219 |
+
# ------------------------------------------------------------------ #
|
| 220 |
+
|
| 221 |
+
async def async_flush_to_disk(self, session_dir: str | Path) -> None:
|
| 222 |
+
"""Non-blocking disk flush — runs flush_to_disk in a thread executor."""
|
| 223 |
+
loop = asyncio.get_event_loop()
|
| 224 |
+
await loop.run_in_executor(None, self.flush_to_disk, session_dir)
|
| 225 |
+
|
| 226 |
+
# ------------------------------------------------------------------ #
|
| 227 |
+
# Internals
|
| 228 |
+
# ------------------------------------------------------------------ #
|
| 229 |
+
|
| 230 |
+
_SENTINEL = object() # class-level sentinel for default TTL detection
|
| 231 |
+
|
| 232 |
+
def __len__(self) -> int:
|
| 233 |
+
return len(self._store)
|
| 234 |
+
|
| 235 |
+
def __contains__(self, key: str) -> bool:
|
| 236 |
+
entry = self._store.get(key)
|
| 237 |
+
if entry is None:
|
| 238 |
+
return False
|
| 239 |
+
if entry.is_expired():
|
| 240 |
+
del self._store[key]
|
| 241 |
+
return False
|
| 242 |
+
return True
|
|
@@ -0,0 +1,189 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""EventBus — publish/subscribe event system for Polyhedra V4.3.
|
| 2 |
+
|
| 3 |
+
Replaces direct Coordinator dispatch with a lightweight in-process,
|
| 4 |
+
synchronous pub/sub layer. Agents emit events; the Coordinator reacts
|
| 5 |
+
as a subscriber. No external message broker is used in V4.3.
|
| 6 |
+
|
| 7 |
+
All events are dataclasses defined here. Handlers are callables
|
| 8 |
+
(sync or async). publish() detects coroutines and awaits them;
|
| 9 |
+
for synchronous handlers no event loop is required.
|
| 10 |
+
"""
|
| 11 |
+
|
| 12 |
+
from __future__ import annotations
|
| 13 |
+
|
| 14 |
+
import asyncio
|
| 15 |
+
import logging
|
| 16 |
+
from collections import defaultdict
|
| 17 |
+
from dataclasses import dataclass, field
|
| 18 |
+
from typing import Any, Callable
|
| 19 |
+
|
| 20 |
+
logger = logging.getLogger(__name__)
|
| 21 |
+
|
| 22 |
+
|
| 23 |
+
# --------------------------------------------------------------------------- #
|
| 24 |
+
# Event definitions
|
| 25 |
+
# --------------------------------------------------------------------------- #
|
| 26 |
+
|
| 27 |
+
@dataclass
|
| 28 |
+
class AgentCompletedEvent:
|
| 29 |
+
"""Emitted by an agent after it writes its artifact and parses routing JSON."""
|
| 30 |
+
|
| 31 |
+
session_id: str
|
| 32 |
+
agent_role: str
|
| 33 |
+
artifact_path: str | None
|
| 34 |
+
next_role: str | None # from routing JSON; None means chain complete
|
| 35 |
+
reason: str
|
| 36 |
+
depth: int
|
| 37 |
+
content: str = "" # the formatted Slack/CLI message to post
|
| 38 |
+
updates_state: bool = False
|
| 39 |
+
state_patch: dict[str, Any] = field(default_factory=dict)
|
| 40 |
+
checkpoint_required: bool = False
|
| 41 |
+
checkpoint_summary: str = ""
|
| 42 |
+
origin_id: str = "" # chain origin message_id for depth tracking
|
| 43 |
+
|
| 44 |
+
|
| 45 |
+
@dataclass
|
| 46 |
+
class AgentBlockedEvent:
|
| 47 |
+
"""Emitted when an agent cannot proceed due to missing data or context."""
|
| 48 |
+
|
| 49 |
+
session_id: str
|
| 50 |
+
agent_role: str
|
| 51 |
+
reason: str
|
| 52 |
+
missing_artifact: str | None = None
|
| 53 |
+
suggested_role: str | None = None # role that should produce the missing artifact
|
| 54 |
+
content: str = "" # human-readable block message
|
| 55 |
+
|
| 56 |
+
|
| 57 |
+
@dataclass
|
| 58 |
+
class HumanInputRequiredEvent:
|
| 59 |
+
"""Emitted when an agent routes to @human or flags uncertainty."""
|
| 60 |
+
|
| 61 |
+
session_id: str
|
| 62 |
+
agent_role: str
|
| 63 |
+
question: str
|
| 64 |
+
suggested_templates: list[str] = field(default_factory=list)
|
| 65 |
+
content: str = ""
|
| 66 |
+
|
| 67 |
+
|
| 68 |
+
@dataclass
|
| 69 |
+
class PortfolioAlertEvent:
|
| 70 |
+
"""
|
| 71 |
+
Emitted by PortfolioMonitorAgent on a threshold breach.
|
| 72 |
+
|
| 73 |
+
Handled by Coordinator independently of any running chain (FR-2.4).
|
| 74 |
+
"""
|
| 75 |
+
|
| 76 |
+
session_id: str
|
| 77 |
+
position_id: str
|
| 78 |
+
ticker: str
|
| 79 |
+
alert_type: str # "take_profit" | "stop_loss" | "pct_move"
|
| 80 |
+
current_price: float
|
| 81 |
+
threshold: float
|
| 82 |
+
content: str = "" # pre-formatted Slack alert message
|
| 83 |
+
|
| 84 |
+
|
| 85 |
+
# --------------------------------------------------------------------------- #
|
| 86 |
+
# EventBus
|
| 87 |
+
# --------------------------------------------------------------------------- #
|
| 88 |
+
|
| 89 |
+
Handler = Callable[[Any], Any]
|
| 90 |
+
|
| 91 |
+
|
| 92 |
+
class EventBus:
|
| 93 |
+
"""
|
| 94 |
+
In-process, synchronous publish/subscribe event bus (V4.3).
|
| 95 |
+
|
| 96 |
+
Async handlers *are* supported — publish() detects coroutines and
|
| 97 |
+
schedules them onto the running event loop. If no loop is running
|
| 98 |
+
they are run via asyncio.run().
|
| 99 |
+
|
| 100 |
+
Exceptions raised by handlers are caught, logged, and do not
|
| 101 |
+
propagate to other subscribers (FR-2.6).
|
| 102 |
+
"""
|
| 103 |
+
|
| 104 |
+
def __init__(self) -> None:
|
| 105 |
+
self._subscribers: dict[type, list[Handler]] = defaultdict(list)
|
| 106 |
+
|
| 107 |
+
# ------------------------------------------------------------------ #
|
| 108 |
+
# Subscription management
|
| 109 |
+
# ------------------------------------------------------------------ #
|
| 110 |
+
|
| 111 |
+
def subscribe(self, event_type: type, handler: Handler) -> None:
|
| 112 |
+
"""Register *handler* to be called for every event of *event_type*."""
|
| 113 |
+
if handler not in self._subscribers[event_type]:
|
| 114 |
+
self._subscribers[event_type].append(handler)
|
| 115 |
+
logger.debug("EventBus: subscribed %s to %s", _handler_name(handler), event_type.__name__)
|
| 116 |
+
|
| 117 |
+
def unsubscribe(self, event_type: type, handler: Handler) -> None:
|
| 118 |
+
"""Remove *handler* from *event_type* subscriptions (no-op if not registered)."""
|
| 119 |
+
try:
|
| 120 |
+
self._subscribers[event_type].remove(handler)
|
| 121 |
+
except ValueError:
|
| 122 |
+
pass
|
| 123 |
+
|
| 124 |
+
# ------------------------------------------------------------------ #
|
| 125 |
+
# Publishing
|
| 126 |
+
# ------------------------------------------------------------------ #
|
| 127 |
+
|
| 128 |
+
def publish(self, event: Any) -> None:
|
| 129 |
+
"""
|
| 130 |
+
Deliver *event* to all subscribers registered for its type.
|
| 131 |
+
|
| 132 |
+
Handlers are called in registration order. Exceptions are caught
|
| 133 |
+
and logged per-handler — a failing handler does not stop others.
|
| 134 |
+
"""
|
| 135 |
+
event_type = type(event)
|
| 136 |
+
handlers = list(self._subscribers.get(event_type, []))
|
| 137 |
+
for handler in handlers:
|
| 138 |
+
self._call_handler(handler, event)
|
| 139 |
+
|
| 140 |
+
# ------------------------------------------------------------------ #
|
| 141 |
+
# Internal helpers
|
| 142 |
+
# ------------------------------------------------------------------ #
|
| 143 |
+
|
| 144 |
+
def _call_handler(self, handler: Handler, event: Any) -> None:
|
| 145 |
+
try:
|
| 146 |
+
result = handler(event)
|
| 147 |
+
# Support async handlers
|
| 148 |
+
if asyncio.iscoroutine(result):
|
| 149 |
+
try:
|
| 150 |
+
loop = asyncio.get_event_loop()
|
| 151 |
+
if loop.is_running():
|
| 152 |
+
# Schedule as a task; fire-and-forget for PortfolioAlertEvent
|
| 153 |
+
loop.create_task(result)
|
| 154 |
+
else:
|
| 155 |
+
loop.run_until_complete(result)
|
| 156 |
+
except RuntimeError:
|
| 157 |
+
asyncio.run(result)
|
| 158 |
+
except Exception as exc:
|
| 159 |
+
logger.error(
|
| 160 |
+
"EventBus: handler %s raised exception for %s: %s",
|
| 161 |
+
_handler_name(handler),
|
| 162 |
+
type(event).__name__,
|
| 163 |
+
exc,
|
| 164 |
+
exc_info=True,
|
| 165 |
+
)
|
| 166 |
+
|
| 167 |
+
|
| 168 |
+
def _handler_name(handler: Handler) -> str:
|
| 169 |
+
return getattr(handler, "__qualname__", repr(handler))
|
| 170 |
+
|
| 171 |
+
|
| 172 |
+
# --------------------------------------------------------------------------- #
|
| 173 |
+
# Global session-scoped bus (convenience singleton per-session)
|
| 174 |
+
# --------------------------------------------------------------------------- #
|
| 175 |
+
|
| 176 |
+
# Keyed by session_id — one bus instance per active session.
|
| 177 |
+
_buses: dict[str, EventBus] = {}
|
| 178 |
+
|
| 179 |
+
|
| 180 |
+
def get_bus(session_id: str) -> EventBus:
|
| 181 |
+
"""Return (creating if necessary) the EventBus for *session_id*."""
|
| 182 |
+
if session_id not in _buses:
|
| 183 |
+
_buses[session_id] = EventBus()
|
| 184 |
+
return _buses[session_id]
|
| 185 |
+
|
| 186 |
+
|
| 187 |
+
def clear_bus(session_id: str) -> None:
|
| 188 |
+
"""Destroy the bus for *session_id* (call on session teardown)."""
|
| 189 |
+
_buses.pop(session_id, None)
|
|
@@ -148,6 +148,18 @@ class TradeEvent:
|
|
| 148 |
timestamp: str = dc_field(default_factory=lambda: datetime.now(tz=timezone.utc).isoformat())
|
| 149 |
|
| 150 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 151 |
@dataclass
|
| 152 |
class QuantState:
|
| 153 |
"""
|
|
@@ -173,6 +185,8 @@ class QuantState:
|
|
| 173 |
# V4.2 portfolio monitor fields
|
| 174 |
monitor_paused: bool = False
|
| 175 |
last_monitor_run: str | None = None
|
|
|
|
|
|
|
| 176 |
|
| 177 |
def to_dict(self) -> dict:
|
| 178 |
from dataclasses import asdict as _asdict
|
|
@@ -209,6 +223,10 @@ class QuantState:
|
|
| 209 |
TradeEvent(**{k: v for k, v in e.items() if k in TradeEvent.__dataclass_fields__})
|
| 210 |
for e in data.get("trade_log", [])
|
| 211 |
]
|
|
|
|
|
|
|
|
|
|
|
|
|
| 212 |
return qs
|
| 213 |
|
| 214 |
def to_markdown(self) -> str:
|
|
|
|
| 148 |
timestamp: str = dc_field(default_factory=lambda: datetime.now(tz=timezone.utc).isoformat())
|
| 149 |
|
| 150 |
|
| 151 |
+
@dataclass
|
| 152 |
+
class TokenUsageEntry:
|
| 153 |
+
"""Per-invocation token usage record for cost tracking (V4.3 FR-4.4)."""
|
| 154 |
+
|
| 155 |
+
agent_role: str
|
| 156 |
+
timestamp: str = dc_field(default_factory=lambda: datetime.now(tz=timezone.utc).isoformat())
|
| 157 |
+
prompt_tokens: int = 0
|
| 158 |
+
completion_tokens: int = 0
|
| 159 |
+
estimated_cost_usd: float = 0.0
|
| 160 |
+
cache_hit: bool = False # True if response came from LLM cache
|
| 161 |
+
|
| 162 |
+
|
| 163 |
@dataclass
|
| 164 |
class QuantState:
|
| 165 |
"""
|
|
|
|
| 185 |
# V4.2 portfolio monitor fields
|
| 186 |
monitor_paused: bool = False
|
| 187 |
last_monitor_run: str | None = None
|
| 188 |
+
# V4.3 token usage log
|
| 189 |
+
token_log: list["TokenUsageEntry"] = dc_field(default_factory=list)
|
| 190 |
|
| 191 |
def to_dict(self) -> dict:
|
| 192 |
from dataclasses import asdict as _asdict
|
|
|
|
| 223 |
TradeEvent(**{k: v for k, v in e.items() if k in TradeEvent.__dataclass_fields__})
|
| 224 |
for e in data.get("trade_log", [])
|
| 225 |
]
|
| 226 |
+
qs.token_log = [
|
| 227 |
+
TokenUsageEntry(**{k: v for k, v in e.items() if k in TokenUsageEntry.__dataclass_fields__})
|
| 228 |
+
for e in data.get("token_log", [])
|
| 229 |
+
]
|
| 230 |
return qs
|
| 231 |
|
| 232 |
def to_markdown(self) -> str:
|
|
@@ -0,0 +1,235 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""TokenBudget — per-agent token budget declarations for Polyhedra V4.3.
|
| 2 |
+
|
| 3 |
+
Every agent declares a TokenBudget. The PromptBuilder enforces it by
|
| 4 |
+
trimming context sections to fit within the declared ceiling before any
|
| 5 |
+
LLM call.
|
| 6 |
+
|
| 7 |
+
Priority order (highest → lowest; system/task/routing are never trimmed):
|
| 8 |
+
1. system — role definition + constraints [NEVER trimmed]
|
| 9 |
+
2. task — task instruction block [NEVER trimmed]
|
| 10 |
+
3. routing — routing instruction block [NEVER trimmed]
|
| 11 |
+
4. context — RAG-retrieved artifact chunks [trimmed first]
|
| 12 |
+
5. thread — last N thread messages [trimmed last]
|
| 13 |
+
"""
|
| 14 |
+
|
| 15 |
+
from __future__ import annotations
|
| 16 |
+
|
| 17 |
+
import logging
|
| 18 |
+
from dataclasses import dataclass, field
|
| 19 |
+
|
| 20 |
+
logger = logging.getLogger(__name__)
|
| 21 |
+
|
| 22 |
+
# Characters-per-token ratio used for fast estimation (matches LLMService.estimate_tokens)
|
| 23 |
+
_CHARS_PER_TOKEN = 4
|
| 24 |
+
|
| 25 |
+
|
| 26 |
+
def _count_tokens(text: str) -> int:
|
| 27 |
+
return max(1, len(text) // _CHARS_PER_TOKEN)
|
| 28 |
+
|
| 29 |
+
|
| 30 |
+
# --------------------------------------------------------------------------- #
|
| 31 |
+
# Budget declaration
|
| 32 |
+
# --------------------------------------------------------------------------- #
|
| 33 |
+
|
| 34 |
+
@dataclass
|
| 35 |
+
class TokenBudget:
|
| 36 |
+
"""
|
| 37 |
+
Per-agent token budget declaration.
|
| 38 |
+
|
| 39 |
+
Fields map to named prompt sections. ``total`` is the hard ceiling
|
| 40 |
+
for the full assembled prompt.
|
| 41 |
+
"""
|
| 42 |
+
|
| 43 |
+
system: int = 500 # role + constraints block
|
| 44 |
+
context: int = 2000 # RAG-retrieved artifact chunks
|
| 45 |
+
task: int = 500 # task instruction block
|
| 46 |
+
thread: int = 500 # last N thread messages
|
| 47 |
+
routing: int = 200 # routing block
|
| 48 |
+
total: int = 4000 # hard ceiling for the assembled prompt
|
| 49 |
+
|
| 50 |
+
@property
|
| 51 |
+
def fixed(self) -> int:
|
| 52 |
+
"""Tokens reserved for sections that are never trimmed."""
|
| 53 |
+
return self.system + self.task + self.routing
|
| 54 |
+
|
| 55 |
+
|
| 56 |
+
# Default budget applied when an agent does not declare one (FR-4.1)
|
| 57 |
+
DEFAULT_BUDGET = TokenBudget()
|
| 58 |
+
|
| 59 |
+
|
| 60 |
+
# --------------------------------------------------------------------------- #
|
| 61 |
+
# Chunk type — returned by RagService
|
| 62 |
+
# --------------------------------------------------------------------------- #
|
| 63 |
+
|
| 64 |
+
@dataclass
|
| 65 |
+
class Chunk:
|
| 66 |
+
"""A piece of retrieved artifact content with its metadata."""
|
| 67 |
+
|
| 68 |
+
text: str
|
| 69 |
+
score: float = 1.0
|
| 70 |
+
metadata: dict = field(default_factory=dict)
|
| 71 |
+
|
| 72 |
+
def token_count(self) -> int:
|
| 73 |
+
return _count_tokens(self.text)
|
| 74 |
+
|
| 75 |
+
|
| 76 |
+
# --------------------------------------------------------------------------- #
|
| 77 |
+
# Prompt builder
|
| 78 |
+
# --------------------------------------------------------------------------- #
|
| 79 |
+
|
| 80 |
+
class PromptBuilder:
|
| 81 |
+
"""
|
| 82 |
+
Assemble a budget-enforced prompt from named sections.
|
| 83 |
+
|
| 84 |
+
Usage::
|
| 85 |
+
|
| 86 |
+
builder = PromptBuilder(budget=agent.token_budget)
|
| 87 |
+
builder.set_system(system_text)
|
| 88 |
+
builder.set_task(task_text)
|
| 89 |
+
builder.set_routing(routing_text)
|
| 90 |
+
builder.set_context(rag_chunks) # list[Chunk] — trimmed to budget
|
| 91 |
+
builder.set_thread(thread_text) # trimmed to budget
|
| 92 |
+
prompt = builder.build() # raises PromptOverBudgetError if still too big
|
| 93 |
+
"""
|
| 94 |
+
|
| 95 |
+
def __init__(self, budget: TokenBudget | None = None) -> None:
|
| 96 |
+
self._budget = budget or DEFAULT_BUDGET
|
| 97 |
+
self._system: str = ""
|
| 98 |
+
self._task: str = ""
|
| 99 |
+
self._routing: str = ""
|
| 100 |
+
self._chunks: list[Chunk] = []
|
| 101 |
+
self._thread: str = ""
|
| 102 |
+
|
| 103 |
+
def set_system(self, text: str) -> None:
|
| 104 |
+
self._system = text
|
| 105 |
+
|
| 106 |
+
def set_task(self, text: str) -> None:
|
| 107 |
+
self._task = text
|
| 108 |
+
|
| 109 |
+
def set_routing(self, text: str) -> None:
|
| 110 |
+
self._routing = text
|
| 111 |
+
|
| 112 |
+
def set_context(self, chunks: list[Chunk]) -> None:
|
| 113 |
+
"""Store RAG chunks (pre-sorted by score descending)."""
|
| 114 |
+
self._chunks = sorted(chunks, key=lambda c: c.score, reverse=True)
|
| 115 |
+
|
| 116 |
+
def set_thread(self, text: str) -> None:
|
| 117 |
+
self._thread = text
|
| 118 |
+
|
| 119 |
+
# ------------------------------------------------------------------ #
|
| 120 |
+
# Build
|
| 121 |
+
# ------------------------------------------------------------------ #
|
| 122 |
+
|
| 123 |
+
def build(self) -> str:
|
| 124 |
+
"""
|
| 125 |
+
Assemble the prompt, enforcing the declared budget.
|
| 126 |
+
|
| 127 |
+
Steps:
|
| 128 |
+
1. Verify fixed sections fit (never trim these).
|
| 129 |
+
2. Fill context allocation with RAG chunks (drop lowest scores first).
|
| 130 |
+
3. Fill thread allocation (trim oldest messages first).
|
| 131 |
+
4. Verify total does not exceed budget.total.
|
| 132 |
+
Returns the assembled prompt string.
|
| 133 |
+
Raises PromptOverBudgetError if it still exceeds the ceiling.
|
| 134 |
+
"""
|
| 135 |
+
budget = self._budget
|
| 136 |
+
|
| 137 |
+
# -- Fixed sections -------------------------------------------------
|
| 138 |
+
fixed_tokens = (
|
| 139 |
+
_count_tokens(self._system)
|
| 140 |
+
+ _count_tokens(self._task)
|
| 141 |
+
+ _count_tokens(self._routing)
|
| 142 |
+
)
|
| 143 |
+
|
| 144 |
+
# -- Context (RAG chunks) -------------------------------------------
|
| 145 |
+
context_budget = budget.context
|
| 146 |
+
selected_chunks: list[Chunk] = []
|
| 147 |
+
used_context_tokens = 0
|
| 148 |
+
for chunk in self._chunks:
|
| 149 |
+
ct = chunk.token_count()
|
| 150 |
+
if used_context_tokens + ct <= context_budget:
|
| 151 |
+
selected_chunks.append(chunk)
|
| 152 |
+
used_context_tokens += ct
|
| 153 |
+
# else: drop lowest-score chunks (they're already sorted desc, so
|
| 154 |
+
# once we overflow we stop — remaining are lower score)
|
| 155 |
+
|
| 156 |
+
context_text = "\n\n".join(c.text for c in selected_chunks)
|
| 157 |
+
|
| 158 |
+
# -- Thread ---------------------------------------------------------
|
| 159 |
+
thread_budget = budget.thread
|
| 160 |
+
thread_text = self._trim_thread(self._thread, thread_budget)
|
| 161 |
+
|
| 162 |
+
# -- Total check ----------------------------------------------------
|
| 163 |
+
assembled = self._assemble(self._system, self._task, self._routing, context_text, thread_text)
|
| 164 |
+
total_tokens = _count_tokens(assembled)
|
| 165 |
+
|
| 166 |
+
if total_tokens > budget.total:
|
| 167 |
+
# Last resort: trim thread further
|
| 168 |
+
overage = total_tokens - budget.total
|
| 169 |
+
trimmed_thread_budget = max(0, thread_budget - overage * _CHARS_PER_TOKEN)
|
| 170 |
+
thread_text = self._trim_thread(self._thread, trimmed_thread_budget)
|
| 171 |
+
assembled = self._assemble(self._system, self._task, self._routing, context_text, thread_text)
|
| 172 |
+
total_tokens = _count_tokens(assembled)
|
| 173 |
+
|
| 174 |
+
if total_tokens > budget.total:
|
| 175 |
+
raise PromptOverBudgetError(
|
| 176 |
+
f"Prompt ({total_tokens} tokens) exceeds budget total ({budget.total} tokens) "
|
| 177 |
+
f"even after trimming context and thread."
|
| 178 |
+
)
|
| 179 |
+
|
| 180 |
+
logger.debug(
|
| 181 |
+
"PromptBuilder: assembled prompt — "
|
| 182 |
+
"system=%d task=%d routing=%d context=%d thread=%d total=%d (budget=%d)",
|
| 183 |
+
_count_tokens(self._system),
|
| 184 |
+
_count_tokens(self._task),
|
| 185 |
+
_count_tokens(self._routing),
|
| 186 |
+
_count_tokens(context_text),
|
| 187 |
+
_count_tokens(thread_text),
|
| 188 |
+
total_tokens,
|
| 189 |
+
budget.total,
|
| 190 |
+
)
|
| 191 |
+
return assembled
|
| 192 |
+
|
| 193 |
+
# ------------------------------------------------------------------ #
|
| 194 |
+
# Internals
|
| 195 |
+
# ------------------------------------------------------------------ #
|
| 196 |
+
|
| 197 |
+
@staticmethod
|
| 198 |
+
def _trim_thread(thread: str, token_budget: int) -> str:
|
| 199 |
+
"""
|
| 200 |
+
Trim *thread* to *token_budget* by dropping oldest lines first.
|
| 201 |
+
Returns as much of the *end* of the thread as fits.
|
| 202 |
+
"""
|
| 203 |
+
if not thread:
|
| 204 |
+
return ""
|
| 205 |
+
char_limit = token_budget * _CHARS_PER_TOKEN
|
| 206 |
+
if len(thread) <= char_limit:
|
| 207 |
+
return thread
|
| 208 |
+
# Drop from the front (oldest messages)
|
| 209 |
+
return "…\n" + thread[-char_limit:]
|
| 210 |
+
|
| 211 |
+
@staticmethod
|
| 212 |
+
def _assemble(system: str, task: str, routing: str, context: str, thread: str) -> str:
|
| 213 |
+
parts: list[str] = []
|
| 214 |
+
if system:
|
| 215 |
+
parts.append(f"## [1] ROLE\n{system}")
|
| 216 |
+
if context:
|
| 217 |
+
parts.append(f"## [2] CONTEXT\n{context}")
|
| 218 |
+
if thread:
|
| 219 |
+
parts.append(f"## [3] THREAD\n{thread}")
|
| 220 |
+
if task:
|
| 221 |
+
parts.append(f"## [4] TASK\n{task}")
|
| 222 |
+
if routing:
|
| 223 |
+
parts.append(f"## [5] ROUTING\n{routing}")
|
| 224 |
+
return "\n\n".join(parts)
|
| 225 |
+
|
| 226 |
+
|
| 227 |
+
# --------------------------------------------------------------------------- #
|
| 228 |
+
# Errors
|
| 229 |
+
# --------------------------------------------------------------------------- #
|
| 230 |
+
|
| 231 |
+
class PromptOverBudgetError(Exception):
|
| 232 |
+
"""
|
| 233 |
+
Raised when a prompt cannot fit within the declared budget even after
|
| 234 |
+
trimming context and thread sections (FR-4.3).
|
| 235 |
+
"""
|
|
@@ -1,8 +1,15 @@
|
|
| 1 |
-
"""FileWriter — shared file I/O service for Polyhedra V4.
|
| 2 |
|
| 3 |
Every agent reads and writes quant artifacts exclusively through this service.
|
| 4 |
No agent ever constructs an absolute path or calls open() directly.
|
| 5 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 6 |
All paths are relative to the session directory
|
| 7 |
(~/.polyhedra/sessions/<session_id>/).
|
| 8 |
"""
|
|
@@ -11,6 +18,11 @@ from __future__ import annotations
|
|
| 11 |
|
| 12 |
import logging
|
| 13 |
from pathlib import Path
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 14 |
|
| 15 |
logger = logging.getLogger(__name__)
|
| 16 |
|
|
@@ -21,48 +33,131 @@ class FileWriter:
|
|
| 21 |
|
| 22 |
Every method takes a path *relative to the session directory*.
|
| 23 |
Parent directories are created automatically on write.
|
|
|
|
|
|
|
|
|
|
| 24 |
"""
|
| 25 |
|
| 26 |
-
def __init__(
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 27 |
self._base = session_dir
|
|
|
|
|
|
|
|
|
|
| 28 |
|
| 29 |
# ------------------------------------------------------------------ #
|
| 30 |
# Public API
|
| 31 |
# ------------------------------------------------------------------ #
|
| 32 |
|
| 33 |
def read(self, path: str) -> str | None:
|
| 34 |
-
"""
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 35 |
full = self._base / path
|
| 36 |
if not full.exists():
|
| 37 |
return None
|
| 38 |
try:
|
| 39 |
-
|
| 40 |
except Exception as exc:
|
| 41 |
logger.warning("FileWriter.read failed for %s: %s", path, exc)
|
| 42 |
return None
|
| 43 |
|
| 44 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 45 |
"""
|
| 46 |
-
Write content to path.
|
|
|
|
|
|
|
|
|
|
|
|
|
| 47 |
|
| 48 |
Args:
|
| 49 |
-
path:
|
| 50 |
-
content:
|
| 51 |
-
mode:
|
| 52 |
-
|
|
|
|
|
|
|
|
|
|
| 53 |
"""
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 54 |
full = self._base / path
|
| 55 |
full.parent.mkdir(parents=True, exist_ok=True)
|
| 56 |
try:
|
| 57 |
if mode == "append":
|
| 58 |
with full.open("a", encoding="utf-8") as fh:
|
| 59 |
fh.write(content)
|
| 60 |
-
|
| 61 |
-
|
|
|
|
|
|
|
| 62 |
except Exception as exc:
|
| 63 |
logger.error("FileWriter.write failed for %s: %s", path, exc)
|
| 64 |
raise
|
| 65 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 66 |
def list(self, prefix: str) -> list[str]:
|
| 67 |
"""Return all file paths under *prefix*, relative to the session dir."""
|
| 68 |
base = self._base / prefix
|
|
@@ -77,3 +172,21 @@ class FileWriter:
|
|
| 77 |
def exists(self, path: str) -> bool:
|
| 78 |
"""Return True if the artifact exists."""
|
| 79 |
return (self._base / path).exists()
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
"""FileWriter — shared file I/O service for Polyhedra V4.3.
|
| 2 |
|
| 3 |
Every agent reads and writes quant artifacts exclusively through this service.
|
| 4 |
No agent ever constructs an absolute path or calls open() directly.
|
| 5 |
|
| 6 |
+
V4.3 changes:
|
| 7 |
+
- read() checks SharedCache first; on miss reads disk and populates cache.
|
| 8 |
+
- write() updates SharedCache AND disk simultaneously (FR-1.2).
|
| 9 |
+
- write() calls rag_service.index_artifact() on every write (FR-3.1).
|
| 10 |
+
- write() invalidates artifact:* cache keys for affected tickers (FR-1.6)
|
| 11 |
+
when the writing agent is "datafetcher".
|
| 12 |
+
|
| 13 |
All paths are relative to the session directory
|
| 14 |
(~/.polyhedra/sessions/<session_id>/).
|
| 15 |
"""
|
|
|
|
| 18 |
|
| 19 |
import logging
|
| 20 |
from pathlib import Path
|
| 21 |
+
from typing import TYPE_CHECKING
|
| 22 |
+
|
| 23 |
+
if TYPE_CHECKING:
|
| 24 |
+
from polyhedra.core.cache import SharedCache
|
| 25 |
+
from polyhedra.services.rag_service import RAGService
|
| 26 |
|
| 27 |
logger = logging.getLogger(__name__)
|
| 28 |
|
|
|
|
| 33 |
|
| 34 |
Every method takes a path *relative to the session directory*.
|
| 35 |
Parent directories are created automatically on write.
|
| 36 |
+
|
| 37 |
+
V4.3: Inject ``cache`` and ``rag`` at construction time or leave them
|
| 38 |
+
as None for backward compatibility (cache/RAG disabled, pure disk I/O).
|
| 39 |
"""
|
| 40 |
|
| 41 |
+
def __init__(
|
| 42 |
+
self,
|
| 43 |
+
session_dir: Path,
|
| 44 |
+
session_id: str = "",
|
| 45 |
+
cache: "SharedCache | None" = None,
|
| 46 |
+
rag: "RAGService | None" = None,
|
| 47 |
+
) -> None:
|
| 48 |
self._base = session_dir
|
| 49 |
+
self._session_id = session_id
|
| 50 |
+
self._cache = cache
|
| 51 |
+
self._rag = rag
|
| 52 |
|
| 53 |
# ------------------------------------------------------------------ #
|
| 54 |
# Public API
|
| 55 |
# ------------------------------------------------------------------ #
|
| 56 |
|
| 57 |
def read(self, path: str) -> str | None:
|
| 58 |
+
"""
|
| 59 |
+
Return file contents, checking SharedCache first (FR-1.3).
|
| 60 |
+
|
| 61 |
+
On cache miss, reads from disk and populates the cache before
|
| 62 |
+
returning. Returns None if the file does not exist.
|
| 63 |
+
"""
|
| 64 |
+
if self._cache is not None:
|
| 65 |
+
cache_key = f"artifact:{self._session_id}:{path}"
|
| 66 |
+
cached = self._cache.get(cache_key)
|
| 67 |
+
if cached is not None:
|
| 68 |
+
return cached
|
| 69 |
+
|
| 70 |
full = self._base / path
|
| 71 |
if not full.exists():
|
| 72 |
return None
|
| 73 |
try:
|
| 74 |
+
content = full.read_text(encoding="utf-8")
|
| 75 |
except Exception as exc:
|
| 76 |
logger.warning("FileWriter.read failed for %s: %s", path, exc)
|
| 77 |
return None
|
| 78 |
|
| 79 |
+
# Populate cache on disk-read so next access is cache-hit
|
| 80 |
+
if self._cache is not None:
|
| 81 |
+
self._cache.set(f"artifact:{self._session_id}:{path}", content)
|
| 82 |
+
|
| 83 |
+
return content
|
| 84 |
+
|
| 85 |
+
def write(
|
| 86 |
+
self,
|
| 87 |
+
path: str,
|
| 88 |
+
content: str,
|
| 89 |
+
mode: str = "overwrite",
|
| 90 |
+
agent_role: str = "",
|
| 91 |
+
metadata: dict | None = None,
|
| 92 |
+
) -> None:
|
| 93 |
"""
|
| 94 |
+
Write content to path, keeping cache and disk in sync (FR-1.2).
|
| 95 |
+
|
| 96 |
+
Also indexes the artifact into RagService automatically (FR-3.1).
|
| 97 |
+
Passing ``agent_role="datafetcher"`` triggers cache invalidation of
|
| 98 |
+
all ``artifact:*`` keys for matching tickers (FR-1.6).
|
| 99 |
|
| 100 |
Args:
|
| 101 |
+
path: Relative path under the session directory.
|
| 102 |
+
content: Text to write.
|
| 103 |
+
mode: ``"overwrite"`` (default) replaces the file.
|
| 104 |
+
``"append"`` appends to the end.
|
| 105 |
+
agent_role: Role of the writing agent — used for RAG metadata
|
| 106 |
+
and DataFetcher cache invalidation.
|
| 107 |
+
metadata: Extra RAG metadata (e.g. ``{"ticker": "GLD"}``).
|
| 108 |
"""
|
| 109 |
+
final_content = self._write_to_disk(path, content, mode)
|
| 110 |
+
self._update_cache(path, final_content, agent_role)
|
| 111 |
+
self._index_into_rag(path, final_content, agent_role, metadata)
|
| 112 |
+
|
| 113 |
+
def _write_to_disk(self, path: str, content: str, mode: str) -> str:
|
| 114 |
+
"""Write to disk and return the final content (accounting for appends)."""
|
| 115 |
full = self._base / path
|
| 116 |
full.parent.mkdir(parents=True, exist_ok=True)
|
| 117 |
try:
|
| 118 |
if mode == "append":
|
| 119 |
with full.open("a", encoding="utf-8") as fh:
|
| 120 |
fh.write(content)
|
| 121 |
+
cached = (self._cache.get(f"artifact:{self._session_id}:{path}") or "") if self._cache else ""
|
| 122 |
+
return cached + content
|
| 123 |
+
full.write_text(content, encoding="utf-8")
|
| 124 |
+
return content
|
| 125 |
except Exception as exc:
|
| 126 |
logger.error("FileWriter.write failed for %s: %s", path, exc)
|
| 127 |
raise
|
| 128 |
|
| 129 |
+
def _update_cache(self, path: str, final_content: str, agent_role: str) -> None:
|
| 130 |
+
"""Sync cache after a write (FR-1.2) and invalidate on DataFetcher writes (FR-1.6)."""
|
| 131 |
+
if self._cache is None:
|
| 132 |
+
return
|
| 133 |
+
self._cache.set(f"artifact:{self._session_id}:{path}", final_content)
|
| 134 |
+
if agent_role == "datafetcher":
|
| 135 |
+
ticker = _extract_ticker_from_path(path)
|
| 136 |
+
if ticker:
|
| 137 |
+
self._cache.invalidate_prefix(f"artifact:{self._session_id}:quant/")
|
| 138 |
+
logger.debug("FileWriter: invalidated quant/ cache for datafetcher write (%s)", ticker)
|
| 139 |
+
|
| 140 |
+
def _index_into_rag(self, path: str, content: str, agent_role: str, metadata: dict | None) -> None:
|
| 141 |
+
"""Auto-index artifact into RagService (FR-3.1)."""
|
| 142 |
+
if self._rag is None:
|
| 143 |
+
return
|
| 144 |
+
from datetime import date
|
| 145 |
+
rag_meta: dict = {
|
| 146 |
+
"session_id": self._session_id,
|
| 147 |
+
"agent_role": agent_role,
|
| 148 |
+
"artifact_path": path,
|
| 149 |
+
"date": date.today().isoformat(),
|
| 150 |
+
}
|
| 151 |
+
if metadata:
|
| 152 |
+
rag_meta.update(metadata)
|
| 153 |
+
ticker = _extract_ticker_from_path(path)
|
| 154 |
+
if ticker:
|
| 155 |
+
rag_meta["ticker"] = ticker
|
| 156 |
+
try:
|
| 157 |
+
self._rag.index_artifact(path, content, rag_meta)
|
| 158 |
+
except Exception as exc:
|
| 159 |
+
logger.warning("FileWriter: RAG index_artifact failed for %s: %s", path, exc)
|
| 160 |
+
|
| 161 |
def list(self, prefix: str) -> list[str]:
|
| 162 |
"""Return all file paths under *prefix*, relative to the session dir."""
|
| 163 |
base = self._base / prefix
|
|
|
|
| 172 |
def exists(self, path: str) -> bool:
|
| 173 |
"""Return True if the artifact exists."""
|
| 174 |
return (self._base / path).exists()
|
| 175 |
+
|
| 176 |
+
|
| 177 |
+
# --------------------------------------------------------------------------- #
|
| 178 |
+
# Helpers
|
| 179 |
+
# --------------------------------------------------------------------------- #
|
| 180 |
+
|
| 181 |
+
def _extract_ticker_from_path(path: str) -> str | None:
|
| 182 |
+
"""
|
| 183 |
+
Extract a ticker symbol from an artifact path such as
|
| 184 |
+
``quant/raw/GLD_2026-03-26.json`` → ``"GLD"``.
|
| 185 |
+
Returns None if no ticker is detected.
|
| 186 |
+
"""
|
| 187 |
+
filename = path.split("/")[-1]
|
| 188 |
+
parts = filename.split("_")
|
| 189 |
+
if parts and parts[0].isupper() and 2 <= len(parts[0]) <= 5:
|
| 190 |
+
return parts[0]
|
| 191 |
+
return None
|
| 192 |
+
|
|
@@ -143,3 +143,144 @@ class RAGService:
|
|
| 143 |
results.append(result)
|
| 144 |
|
| 145 |
return results
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 143 |
results.append(result)
|
| 144 |
|
| 145 |
return results
|
| 146 |
+
|
| 147 |
+
# ------------------------------------------------------------------ #
|
| 148 |
+
# V4.3 — Quant artifact RAG methods (FR-3.1 – FR-3.5)
|
| 149 |
+
# ------------------------------------------------------------------ #
|
| 150 |
+
|
| 151 |
+
def index_artifact(self, path: str, content: str, metadata: dict) -> None:
|
| 152 |
+
"""
|
| 153 |
+
Index a quant artifact for later retrieval (FR-3.1).
|
| 154 |
+
|
| 155 |
+
Called automatically by FileWriter.write() on every artifact write.
|
| 156 |
+
Agents do not call this directly.
|
| 157 |
+
|
| 158 |
+
Args:
|
| 159 |
+
path: Artifact path relative to the session dir (used as doc_id).
|
| 160 |
+
content: Full text content of the artifact.
|
| 161 |
+
metadata: At minimum ``session_id``, ``agent_role``, ``artifact_path``,
|
| 162 |
+
``date``. ``ticker`` is included when applicable.
|
| 163 |
+
"""
|
| 164 |
+
if not content or not content.strip():
|
| 165 |
+
return
|
| 166 |
+
|
| 167 |
+
chunks = _split_chunks(content, chunk_size=500, overlap=50)
|
| 168 |
+
if self._artifact_index is None:
|
| 169 |
+
self._artifact_index = {"texts": [], "metadata": []}
|
| 170 |
+
|
| 171 |
+
for chunk_text in chunks:
|
| 172 |
+
chunk_meta = {**metadata, "artifact_path": path, "chunk_text": chunk_text}
|
| 173 |
+
self._artifact_index["texts"].append(chunk_text)
|
| 174 |
+
self._artifact_index["metadata"].append(chunk_meta)
|
| 175 |
+
|
| 176 |
+
def query_artifacts(
|
| 177 |
+
self,
|
| 178 |
+
question: str,
|
| 179 |
+
top_k: int = 5,
|
| 180 |
+
filter: dict | None = None,
|
| 181 |
+
) -> list[dict]:
|
| 182 |
+
"""
|
| 183 |
+
Retrieve the most relevant artifact chunks for a query (FR-3.2).
|
| 184 |
+
|
| 185 |
+
Unlike ``query()`` which searches indexed academic papers, this
|
| 186 |
+
method searches quant artifact chunks (trend analysis, backtest
|
| 187 |
+
results, etc.) written during the current session.
|
| 188 |
+
|
| 189 |
+
Args:
|
| 190 |
+
question: Natural language query (e.g. "OHLCV data for GLD today").
|
| 191 |
+
top_k: Maximum number of chunks to return.
|
| 192 |
+
filter: Optional metadata filter dict. Every key/value pair in
|
| 193 |
+
*filter* must match the chunk's metadata to be included.
|
| 194 |
+
Example: ``{"ticker": "GLD", "agent_role": "datafetcher"}``
|
| 195 |
+
|
| 196 |
+
Returns:
|
| 197 |
+
List of dicts with ``text``, ``relevance_score``, and ``metadata``
|
| 198 |
+
keys, sorted by relevance descending.
|
| 199 |
+
"""
|
| 200 |
+
if self._artifact_index is None or not self._artifact_index["texts"]:
|
| 201 |
+
return []
|
| 202 |
+
|
| 203 |
+
texts: list[str] = self._artifact_index["texts"]
|
| 204 |
+
metadata: list[dict] = self._artifact_index["metadata"]
|
| 205 |
+
|
| 206 |
+
# Apply metadata filter
|
| 207 |
+
if filter:
|
| 208 |
+
indices = [
|
| 209 |
+
i for i, m in enumerate(metadata)
|
| 210 |
+
if all(m.get(k) == v for k, v in filter.items())
|
| 211 |
+
]
|
| 212 |
+
if not indices:
|
| 213 |
+
return []
|
| 214 |
+
texts_f = [texts[i] for i in indices]
|
| 215 |
+
meta_f = [metadata[i] for i in indices]
|
| 216 |
+
else:
|
| 217 |
+
texts_f = texts
|
| 218 |
+
meta_f = metadata
|
| 219 |
+
|
| 220 |
+
model = self._load_model()
|
| 221 |
+
query_emb = model.encode([question], convert_to_numpy=True)[0]
|
| 222 |
+
chunk_embs = model.encode(texts_f, convert_to_numpy=True, show_progress_bar=False)
|
| 223 |
+
|
| 224 |
+
similarities = np.dot(chunk_embs, query_emb) / (
|
| 225 |
+
np.linalg.norm(chunk_embs, axis=1) * np.linalg.norm(query_emb) + 1e-9
|
| 226 |
+
)
|
| 227 |
+
|
| 228 |
+
top_k_real = min(top_k, len(similarities))
|
| 229 |
+
top_idx = np.argsort(similarities)[-top_k_real:][::-1]
|
| 230 |
+
|
| 231 |
+
return [
|
| 232 |
+
{
|
| 233 |
+
"text": texts_f[idx],
|
| 234 |
+
"relevance_score": float(similarities[idx]),
|
| 235 |
+
"metadata": meta_f[idx],
|
| 236 |
+
}
|
| 237 |
+
for idx in top_idx
|
| 238 |
+
]
|
| 239 |
+
|
| 240 |
+
def rebuild_artifact_index_from_disk(self, session_dir: Any) -> None:
|
| 241 |
+
"""
|
| 242 |
+
Rebuild the in-memory artifact index from all .md files in
|
| 243 |
+
*session_dir* (FR-3.4 — cold-start recovery).
|
| 244 |
+
"""
|
| 245 |
+
from pathlib import Path
|
| 246 |
+
base = Path(session_dir)
|
| 247 |
+
if not base.exists():
|
| 248 |
+
return
|
| 249 |
+
|
| 250 |
+
self._artifact_index = {"texts": [], "metadata": []}
|
| 251 |
+
for artifact_path in sorted(base.rglob("*.md")):
|
| 252 |
+
try:
|
| 253 |
+
content = artifact_path.read_text(encoding="utf-8")
|
| 254 |
+
rel_path = str(artifact_path.relative_to(base)).replace("\\", "/")
|
| 255 |
+
self.index_artifact(
|
| 256 |
+
path=rel_path,
|
| 257 |
+
content=content,
|
| 258 |
+
metadata={"artifact_path": rel_path, "source": "disk_rebuild"},
|
| 259 |
+
)
|
| 260 |
+
except Exception:
|
| 261 |
+
pass
|
| 262 |
+
|
| 263 |
+
@property
|
| 264 |
+
def _artifact_index(self) -> dict | None:
|
| 265 |
+
return getattr(self, "_artifact_index_store", None)
|
| 266 |
+
|
| 267 |
+
@_artifact_index.setter
|
| 268 |
+
def _artifact_index(self, value: dict | None) -> None:
|
| 269 |
+
self._artifact_index_store = value
|
| 270 |
+
|
| 271 |
+
|
| 272 |
+
# --------------------------------------------------------------------------- #
|
| 273 |
+
# Module-level helpers
|
| 274 |
+
# --------------------------------------------------------------------------- #
|
| 275 |
+
|
| 276 |
+
def _split_chunks(text: str, chunk_size: int = 500, overlap: int = 50) -> list[str]:
|
| 277 |
+
"""Split *text* into overlapping character-level chunks."""
|
| 278 |
+
if len(text) <= chunk_size:
|
| 279 |
+
return [text]
|
| 280 |
+
chunks: list[str] = []
|
| 281 |
+
start = 0
|
| 282 |
+
while start < len(text):
|
| 283 |
+
end = start + chunk_size
|
| 284 |
+
chunks.append(text[start:end])
|
| 285 |
+
start += chunk_size - overlap
|
| 286 |
+
return chunks
|