yf176 commited on
Commit
8da9286
·
1 Parent(s): 1b0450e

docs: focus readme on v6 quant workflow

Browse files
Files changed (1) hide show
  1. README.md +15 -386
README.md CHANGED
@@ -63,21 +63,7 @@ Polyhedra is a Slack-native multi-agent paper-trading system. V6 preserves the V
63
 
64
  ---
65
 
66
- ## The Agent Teams
67
-
68
- ### Research Team (Legacy)
69
-
70
- Academic research agents are legacy modules and are not the V6 product focus.
71
-
72
- | Agent | Role | Responsibility |
73
- |-------|------|----------------|
74
- | **Scout** | Literature Researcher | Searches Semantic Scholar (200M+ papers), formats results |
75
- | **Strategist** | Research Designer | Proposes up to 3 research directions via LLM |
76
- | **Critic** | Devil's Advocate | 4-section review (Strengths / Weaknesses / Missing / Publishable path) |
77
- | **Scribe** | Writer / Editor | Drafts paper sections, saves to `artifacts/` |
78
- | **Coordinator** | Orchestrator | Routes @mentions, gates costs, enforces loop limit (depth 3), updates state |
79
-
80
- ### Quant Team (V5/V6)
81
 
82
  | Agent | Responsibility |
83
  |-------|---------------|
@@ -132,20 +118,7 @@ export SLACK_SIGNING_SECRET=...
132
  export POLYHEDRA_QUANT_WATCHLIST=AAPL,MSFT,NVDA,GOOGL
133
  ```
134
 
135
- ### 3. Research session (CLI)
136
-
137
- ```bash
138
- poly init "Efficient transformers for long-context NLP"
139
- ```
140
-
141
- ```
142
- you> @scout search for sparse attention mechanisms
143
- you> @strategist propose three research directions
144
- you> @scribe draft the Introduction section
145
- you> /quit
146
- ```
147
-
148
- ### 4. Quant paper-trading session (Slack)
149
 
150
  ```
151
  /poly init paper trading session
@@ -165,41 +138,13 @@ The bot will fetch market data, run the full quant pipeline, and post a trade su
165
 
166
  ---
167
 
168
- ## CLI Reference
169
-
170
- ```
171
- poly init <goal> Start a new research session
172
- poly search <query> Quick paper search (no session needed)
173
- poly state Show the current Research State
174
- poly resume Resume the last session (or pick from a list)
175
- poly export Export a session as .zip
176
- poly role <name> human Take over an agent role
177
- poly role <name> agent Restore an agent to its role
178
- poly sessions List all saved sessions
179
- poly mcp Start the legacy MCP server
180
- ```
181
-
182
- ---
183
-
184
  ## Slack Commands
185
 
186
- ### Research
187
-
188
- ```
189
- /poly init <goal>
190
- /poly state
191
- /poly role critic human
192
- /poly export
193
- @Bot @scout search transformers for video
194
- ```
195
-
196
- ### Quant paper trading
197
-
198
  ```
199
  /poly watchlist add <TICKER>
200
  /poly watchlist remove <TICKER>
201
  /poly watchlist show
202
- /poly quant ← run full quant pipeline on watchlist
203
  /poly portfolio ← summary of open paper positions
204
  /poly trade approve|reject|revise <id> ← act on a trade proposal
205
  /poly trade close <id> ← close an open position (fetches live price)
@@ -212,71 +157,6 @@ All slash commands are also available as `@BotName <command> <args>`.
212
 
213
  ---
214
 
215
- ## IDE Integration (MCP)
216
-
217
- ### VS Code / GitHub Copilot
218
-
219
- ```json
220
- // .vscode/settings.json
221
- {
222
- "mcp.servers": {
223
- "polyhedra": {
224
- "command": "python",
225
- "args": ["-m", "polyhedra.server"]
226
- }
227
- }
228
- }
229
- ```
230
-
231
- ### Cursor / Windsurf
232
-
233
- ```json
234
- // ~/.cursor/mcp.json or ~/.windsurf/mcp.json
235
- {
236
- "mcpServers": {
237
- "polyhedra": {
238
- "command": "python",
239
- "args": ["-m", "polyhedra.server"]
240
- }
241
- }
242
- }
243
- ```
244
-
245
- ---
246
-
247
- ## MCP Tools (v2.x, backward compatible)
248
-
249
- | Tool | Description |
250
- |------|-------------|
251
- | `search_papers` | Search Semantic Scholar |
252
- | `get_paper` | Get full paper details |
253
- | `query_similar_papers` | RAG-based similar paper search |
254
- | `index_papers` | Build semantic search index |
255
- | `add_citation` | Add BibTeX to `references.bib` |
256
- | `get_citations` | List all citations |
257
- | `save_file` | Write project files |
258
- | `get_context` | Read project files |
259
- | `get_project_status` | Project overview |
260
- | `init_project` | Scaffold research structure |
261
- | `generate_literature_review` | AI-generated structured review |
262
- | `estimate_review_cost` | LLM cost estimate before generation |
263
-
264
- ---
265
-
266
- ## Two Execution Models
267
-
268
- Polyhedra ships two distinct execution systems that share a repo but serve very different purposes:
269
-
270
- **`agent/` — Standalone Workflow Engine (MCP / IDE Integration)**
271
- Used by the `poly` CLI and the VS Code / Cursor MCP server (`server.py`). Designed for structured, tool-call-based research workflows where a single user interacts with a sequence of steps. Entry point: `polyhedra.server`. This system has no Slack dependency and is the right choice when integrating Polyhedra into an IDE.
272
-
273
- **`agents/` — Multi-Agent Orchestration System (Slack / CLI Session)**
274
- Used by the Slack integration (`messaging/slack.py`) and the interactive `poly` CLI session. Runs the quant pipeline (DataFetcher → QuantStrategist) and the research team (Scout → Scribe) via `@mention` routing, through a shared `CoordinatorService`. This is the system described in the Quick Start and Slack Commands sections above. Do not import from `agent/` (workflow engine) inside this module.
275
-
276
- > **Rule of thumb:** Building an IDE assistant or an automated pipeline without Slack? Use `agent/`. Running an interactive session with Slack slash commands or the multi-agent quant pipeline? Use `agents/`.
277
-
278
- ---
279
-
280
  ## Architecture
281
 
282
  ```
@@ -284,20 +164,19 @@ src/polyhedra/
284
  agents/
285
  base.py # Agent ABC, Mention, AgentResponse
286
  coordinator.py # CoordinatorAgent + CoordinatorService
287
- scout.py # Literature Researcher
288
- strategist.py # Research Designer
289
- critic.py # Devil's Advocate
290
- scribe.py # Writer / Editor
291
  quant/
292
  datafetcher.py # OHLCV + news + earnings per ticker
293
- technical.py # SMA/EMA/RSI/MACD signal generation
294
- sentiment.py # LLM-scored news sentiment
295
- fundamental.py # Earnings surprise / EPS trend
296
- signal_aggregator.py # Combined net signal score
297
- risk_manager.py # Position sizing, stop/target, heat check
298
- trade_executor.py # Paper trade logging + pre-trade gates
 
 
 
299
  core/
300
- research_state.py # Shared state (research + quant), auto-compress
301
  role_registry.py # Agent/human role tracking + takeover
302
  session.py # Session lifecycle, JSONL thread log
303
  mention_parser.py # @mention regex extraction
@@ -310,9 +189,6 @@ src/polyhedra/
310
  services/
311
  finnhub.py # Finnhub client (news, earnings; OHLCV via yfinance)
312
  llm.py # LLM provider abstraction
313
- semantic_scholar.py # Paper search
314
- rag.py # Vector index + similarity search
315
- citations.py # BibTeX manager
316
  ```
317
 
318
  **Session storage** — `~/.polyhedra/sessions/<id>/`
@@ -321,8 +197,8 @@ src/polyhedra/
321
  |------|----------|
322
  | `session.json` | Metadata (goal, platform, registered roles) |
323
  | `thread.jsonl` | Append-only message log |
324
- | `research_state.json` | Live Research State (goal, papers, gaps, decisions) |
325
- | `artifacts/` | Scribe section drafts |
326
  | `market_data/` | Per-ticker JSON (OHLCV, news, earnings, indicators) |
327
  | `paper_trades.json` | Simulated trade log |
328
 
@@ -352,250 +228,3 @@ ruff check src tests
352
  ## License
353
 
354
  MIT
355
-
356
-
357
- Polyhedra turns your research workflow into a structured team of AI agents — Scout, Strategist, Critic, and Scribe — coordinated by a human-in-the-loop Coordinator. Agents communicate via `@mention` routing, share a compact Research State, and support human role takeover at any point. Accessible from the **CLI**, **Slack**, or your **IDE via MCP**.
358
-
359
-
360
- ## What's New in v3.1
361
-
362
- | Feature | Description |
363
- |---------|-------------|
364
- | 🤝 Multi-agent team | Four specialized agents collaborating via `@mention` |
365
- | 📋 Coordinator | Routes messages, enforces checkpoints, detects loops |
366
- | 👤 Human role takeover | Claim any agent role and drive that part yourself |
367
- | 📄 Research State | Shared, compressed context (~4k tokens) every agent reads |
368
- | 💰 Cost gate | Estimates LLM cost before each dispatch; pauses if > $0.50 |
369
- | 🖥️ `poly` CLI | Interactive terminal sessions with the full agent team |
370
- | 💬 Slack integration | `/poly` slash commands + `@mention` routing in channels |
371
- | 🚀 FastAPI server | Webhook endpoint for Slack events (`uvicorn polyhedra.app:app`) |
372
- | 💾 Session persistence | Sessions saved to `~/.polyhedra/sessions/` — resume any time |
373
- | 📦 Artifact export | Export a full session (thread + drafts) as a `.zip` |
374
- | ⏸️ Graceful failure | Pipeline pauses on API errors; human can paste results back |
375
-
376
- > **Backward compatible** — all v2.x MCP tools continue to work unchanged.
377
-
378
-
379
- ## The Research Team
380
-
381
- | Agent | Role | Responsibility |
382
- |-------|------|----------------|
383
- | **Scout** | Literature Researcher | Searches Semantic Scholar (200M+ papers), formats results, triggers Strategist |
384
- | **Strategist** | Research Designer | Reads Scout summary + Research State, proposes up to 3 directions via LLM |
385
- | **Critic** | Devil's Advocate | 4-section review (Strengths / Weaknesses / Missing / Path to publishable) |
386
- | **Scribe** | Writer / Editor | Drafts paper sections, saves to `artifacts/`, forwards to Critic |
387
- | **Coordinator** | Orchestrator | Routes @mentions, gates costs, enforces loop limit (depth 3), updates state |
388
-
389
- Any agent role can be taken over by a human at any time (`/poly role <name> human`).
390
-
391
-
392
- ## Quick Start
393
-
394
- ### 1. Install
395
-
396
- ```bash
397
- git clone https://github.com/yf176/polyhedra.git
398
- cd polyhedra
399
- pip install -e .
400
- ```
401
-
402
- ### 2. Set your LLM API key
403
-
404
- Strategist, Critic, and Scribe use an LLM. Scout (Semantic Scholar) works without one.
405
-
406
- ```bash
407
- export ANTHROPIC_API_KEY=sk-ant-your-key # recommended
408
- # or
409
- export OPENAI_API_KEY=sk-your-key
410
- # or for Gemini
411
- export GEMINI_API_KEY=your-key
412
- export POLYHEDRA_LLM_PROVIDER=gemini
413
- ```
414
-
415
- ### 3. Start a CLI session
416
-
417
- ```bash
418
- poly init "Efficient transformers for long-context NLP"
419
- ```
420
-
421
- Then in the interactive prompt:
422
-
423
- ```
424
- you> @scout search for sparse attention mechanisms
425
- you> @strategist propose three research directions
426
- you> @scribe draft the Introduction section
427
- you> /quit
428
- ```
429
-
430
-
431
- ## CLI Reference
432
-
433
- ```
434
- poly init <goal> Start a new research session
435
- poly search <query> Quick paper search (no session needed)
436
- poly state Show the current Research State
437
- poly resume Resume the last session (or pick from a list)
438
- poly export Export a session as .zip
439
- poly role <name> human Take over an agent role
440
- poly role <name> agent Restore an agent to its role
441
- poly sessions List all saved sessions
442
- poly mcp Start the legacy MCP server
443
- ```
444
-
445
-
446
- ## IDE Integration (MCP)
447
-
448
- All v2.x MCP tools remain available via the legacy server.
449
-
450
- ### VS Code / GitHub Copilot
451
-
452
- ```json
453
- // .vscode/settings.json
454
- {
455
- "mcp.servers": {
456
- "polyhedra": {
457
- "command": "python",
458
- "args": ["-m", "polyhedra.server"]
459
- }
460
- }
461
- }
462
- ```
463
-
464
- ### Cursor / Windsurf
465
-
466
- ```json
467
- // ~/.cursor/mcp.json or ~/.windsurf/mcp.json
468
- {
469
- "mcpServers": {
470
- "polyhedra": {
471
- "command": "python",
472
- "args": ["-m", "polyhedra.server"]
473
- }
474
- }
475
- }
476
- ```
477
-
478
-
479
- ## Slack Integration
480
-
481
- ### 1. Configure environment variables
482
-
483
- ```bash
484
- export SLACK_BOT_TOKEN=xoxb-...
485
- export SLACK_SIGNING_SECRET=...
486
- export POLYHEDRA_LLM_PROVIDER=gemini
487
- export GEMINI_API_KEY=...
488
- ```
489
-
490
- ### 2. Start the server
491
-
492
- ```bash
493
- pip install slack-bolt fastapi uvicorn
494
- uvicorn polyhedra.app:app --host 0.0.0.0 --port 8000
495
- ```
496
-
497
- Point your Slack app's **Request URL** to `https://<your-domain>/slack/events`.
498
-
499
- ### 3. Use slash commands in any channel
500
-
501
- ```
502
- /poly init Efficient transformers for long-context NLP
503
- /poly state
504
- /poly role critic human
505
- /poly export
506
- ```
507
-
508
- ### 4. When Scout is rate-limited
509
-
510
- Scout will pause the pipeline and post a manual search URL. You can take over:
511
-
512
- ```
513
- @YourBot @scout results: [paste paper titles and summaries here]
514
- ```
515
-
516
- Scout will format your input and hand off to Strategist automatically.
517
-
518
-
519
- ## MCP Tools (v2.x, backward compatible)
520
-
521
- | Tool | Description |
522
- |------|-------------|
523
- | `search_papers` | Search Semantic Scholar |
524
- | `get_paper` | Get full paper details |
525
- | `query_similar_papers` | RAG-based similar paper search |
526
- | `index_papers` | Build semantic search index |
527
- | `add_citation` | Add BibTeX to `references.bib` |
528
- | `get_citations` | List all citations |
529
- | `save_file` | Write project files |
530
- | `get_context` | Read project files |
531
- | `get_project_status` | Project overview |
532
- | `init_project` | Scaffold research structure |
533
- | `generate_literature_review` | AI-generated structured review |
534
- | `estimate_review_cost` | LLM cost estimate before generation |
535
-
536
-
537
- ## Architecture
538
-
539
- ```
540
- src/polyhedra/
541
- agents/
542
- base.py # Agent ABC, Mention, AgentResponse
543
- coordinator.py # CoordinatorAgent + CoordinatorService
544
- scout.py # Literature Researcher
545
- strategist.py # Research Designer
546
- critic.py # Devil's Advocate
547
- scribe.py # Writer / Editor
548
- core/
549
- research_state.py # Shared state, auto-compress (~4k tokens)
550
- role_registry.py # Agent/human role tracking + takeover
551
- session.py # Session lifecycle, JSONL thread log
552
- mention_parser.py # @mention regex extraction
553
- messaging/
554
- slack.py # Slack Bolt integration
555
- cli/
556
- main.py # poly CLI (Typer + Rich)
557
- app.py # FastAPI server (uvicorn entry point)
558
- server.py # Legacy v2.x MCP server
559
- services/ # LLM, SemanticScholar, RAG, citations
560
- ```
561
-
562
- **Session storage** — `~/.polyhedra/sessions/<id>/`
563
-
564
- | File | Contents |
565
- |------|----------|
566
- | `session.json` | Metadata (goal, platform, registered roles) |
567
- | `thread.jsonl` | Append-only message log |
568
- | `research_state.json` | Live Research State (goal, papers, gaps, decisions) |
569
- | `artifacts/` | Scribe section drafts |
570
-
571
- **Coordinator safeguards**
572
-
573
- - `@mention` chains capped at depth 3 — prevents runaway loops
574
- - Cost gate pauses the chain if estimated LLM spend exceeds $0.50
575
- - 90s agent timeout with one automatic retry
576
- - Pipeline pauses gracefully on API failures (no silent cascades)
577
-
578
-
579
- ## Development
580
-
581
- ```bash
582
- pip install -e ".[dev]"
583
-
584
- # Run all tests
585
- py -3 -m pytest --no-cov
586
-
587
- # Run Phase 1 exit-criteria tests
588
- py -3 -m pytest tests/test_phase1_e2e.py --no-cov -v
589
-
590
- # Type check
591
- mypy src
592
-
593
- # Format / lint
594
- black src tests
595
- ruff check src tests
596
- ```
597
-
598
-
599
- ## License
600
-
601
- MIT
 
63
 
64
  ---
65
 
66
+ ## Quant Agent Team
 
 
 
 
 
 
 
 
 
 
 
 
 
 
67
 
68
  | Agent | Responsibility |
69
  |-------|---------------|
 
118
  export POLYHEDRA_QUANT_WATCHLIST=AAPL,MSFT,NVDA,GOOGL
119
  ```
120
 
121
+ ### 3. Quant paper-trading session (Slack)
 
 
 
 
 
 
 
 
 
 
 
 
 
122
 
123
  ```
124
  /poly init paper trading session
 
138
 
139
  ---
140
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
141
  ## Slack Commands
142
 
 
 
 
 
 
 
 
 
 
 
 
 
143
  ```
144
  /poly watchlist add <TICKER>
145
  /poly watchlist remove <TICKER>
146
  /poly watchlist show
147
+ /poly quant ← run V6 for BTC/SPY/QQQ/GLD, otherwise V5
148
  /poly portfolio ← summary of open paper positions
149
  /poly trade approve|reject|revise <id> ← act on a trade proposal
150
  /poly trade close <id> ← close an open position (fetches live price)
 
157
 
158
  ---
159
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
160
  ## Architecture
161
 
162
  ```
 
164
  agents/
165
  base.py # Agent ABC, Mention, AgentResponse
166
  coordinator.py # CoordinatorAgent + CoordinatorService
 
 
 
 
167
  quant/
168
  datafetcher.py # OHLCV + news + earnings per ticker
169
+ trendanalyst.py # Technical analysis
170
+ sentimentanalyst.py # LLM-scored news sentiment
171
+ market_watchers.py # V6 event, options, macro, detector, router agents
172
+ asset_analysts.py # V6 BTC/SPY/QQQ/GLD specialized analysts
173
+ quantresearcher.py # Signal synthesis
174
+ backtester.py # Signal backtests
175
+ riskanalyst.py # Position sizing, stop/target, heat check
176
+ quantstrategist.py # Paper-trade proposal strategy
177
+ publisher.py # Finley, final Slack output
178
  core/
179
+ research_state.py # Shared session and quant state
180
  role_registry.py # Agent/human role tracking + takeover
181
  session.py # Session lifecycle, JSONL thread log
182
  mention_parser.py # @mention regex extraction
 
189
  services/
190
  finnhub.py # Finnhub client (news, earnings; OHLCV via yfinance)
191
  llm.py # LLM provider abstraction
 
 
 
192
  ```
193
 
194
  **Session storage** — `~/.polyhedra/sessions/<id>/`
 
197
  |------|----------|
198
  | `session.json` | Metadata (goal, platform, registered roles) |
199
  | `thread.jsonl` | Append-only message log |
200
+ | `research_state.json` | Live session and quant state |
201
+ | `quant/` | Agent artifacts for market data, analysis, risk, strategy, and posts |
202
  | `market_data/` | Per-ticker JSON (OHLCV, news, earnings, indicators) |
203
  | `paper_trades.json` | Simulated trade log |
204
 
 
228
  ## License
229
 
230
  MIT