yf176 commited on
Commit
cc23e2a
·
1 Parent(s): dbffe1d

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 CHANGED
@@ -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
  # =============================================================================
docs/polyhedraV4.3.md ADDED
@@ -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
src/polyhedra/agents/base.py CHANGED
@@ -1,4 +1,4 @@
1
- """Agent base class and shared data models for Polyhedra v4.1."""
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))
src/polyhedra/agents/coordinator.py CHANGED
@@ -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
- 1. Appends the message to the session thread.
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 # reset for next segment
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.1: inject FileWriter into agent before handle()
367
- entry.agent.files = FileWriter(self.session.session_dir)
 
 
 
 
 
 
 
368
 
369
- # Cost estimation gate (NFR §5): estimate LLM cost before dispatching
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.1: detect "Skipped" — agent could not proceed due to missing artifact.
413
- # Routing JSON already points at the agent that produces the missing input;
414
- # follow-up dispatch below will route there. Do not apply any state update.
 
 
415
  if response.content.startswith("Skipped —"):
416
- if response.mentions:
417
- follow_up_text = " ".join(f"@{r}" for r in response.mentions)
418
- await self.dispatch(
419
- from_role=entry.role,
420
- text=follow_up_text + " " + response.content[:200],
421
- origin_id=origin_id,
422
- )
 
 
423
  return
424
 
425
- # Update Research State if requested
426
- if response.updates_state:
427
- self._apply_state_update(response)
428
-
429
- # Checkpoint gate
430
- if response.checkpoint_required:
431
- result = await self._checkpoint(response.checkpoint_summary)
432
- if not result.approved:
433
- await self._post(
434
- "coordinator",
435
- "\u23f8 **Coordinator** \u2014 session paused at user's request. "
436
- "Resume anytime with `/poly resume` or by continuing in the thread.",
437
- )
438
- return
439
-
440
- # Follow-up @mentions from agent response
441
- if response.mentions:
442
- follow_up_text = " ".join(f"@{r}" for r in response.mentions)
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))
src/polyhedra/agents/quant/backtester.py CHANGED
@@ -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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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
 
src/polyhedra/agents/quant/portfoliomonitor.py CHANGED
@@ -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,
src/polyhedra/agents/quant/quantresearcher.py CHANGED
@@ -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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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 — proceeding."}'
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
 
src/polyhedra/agents/quant/quantstrategist.py CHANGED
@@ -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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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)
src/polyhedra/agents/quant/riskanalyst.py CHANGED
@@ -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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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 — proceeding."}'
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
 
src/polyhedra/agents/quant/sentimentanalyst.py CHANGED
@@ -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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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 — proceeding with available data."}}'
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
 
src/polyhedra/agents/quant/trendanalyst.py CHANGED
@@ -1,4 +1,4 @@
1
- """TrendAnalystAgent — Technical Analyst for Polyhedra V4.1.
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
- llm_text = result[0] if isinstance(result, tuple) else result
 
 
 
 
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 = (
src/polyhedra/agents/quant/vizagent.py CHANGED
@@ -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
- text = result[0] if isinstance(result, tuple) else result
 
 
 
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})."
src/polyhedra/cli/main.py CHANGED
@@ -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
  # --------------------------------------------------------------------------- #
src/polyhedra/core/__init__.py CHANGED
@@ -1,14 +1,34 @@
1
- """Core package for Polyhedra v3.0."""
2
 
3
- from polyhedra.core.research_state import ResearchState, ResearchStateManager
 
 
 
 
 
 
 
 
 
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
  ]
src/polyhedra/core/cache.py ADDED
@@ -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
src/polyhedra/core/eventbus.py ADDED
@@ -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)
src/polyhedra/core/research_state.py CHANGED
@@ -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:
src/polyhedra/core/token_budget.py ADDED
@@ -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
+ """
src/polyhedra/services/file_writer.py CHANGED
@@ -1,8 +1,15 @@
1
- """FileWriter — shared file I/O service for Polyhedra V4.1.
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__(self, session_dir: Path) -> None:
 
 
 
 
 
 
27
  self._base = session_dir
 
 
 
28
 
29
  # ------------------------------------------------------------------ #
30
  # Public API
31
  # ------------------------------------------------------------------ #
32
 
33
  def read(self, path: str) -> str | None:
34
- """Return file contents, or None if the file does not exist."""
 
 
 
 
 
 
 
 
 
 
 
35
  full = self._base / path
36
  if not full.exists():
37
  return None
38
  try:
39
- return full.read_text(encoding="utf-8")
40
  except Exception as exc:
41
  logger.warning("FileWriter.read failed for %s: %s", path, exc)
42
  return None
43
 
44
- def write(self, path: str, content: str, mode: str = "overwrite") -> None:
 
 
 
 
 
 
 
 
 
 
 
 
 
45
  """
46
- Write content to path.
 
 
 
 
47
 
48
  Args:
49
- path: Relative path under the session directory.
50
- content: Text to write.
51
- mode: ``"overwrite"`` (default) replaces the file.
52
- ``"append"`` appends to the end.
 
 
 
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
- else:
61
- full.write_text(content, encoding="utf-8")
 
 
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
+
src/polyhedra/services/rag_service.py CHANGED
@@ -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