openInvest Wiki
Complete documentation for the multi-asset AI investment committee system. Main repository longsizhuo/openInvest · GUI longsizhuo/invest-gui Homepage README.md · 30-minute fork QUICK_START.md
Choose Your Path by Reader Profile
🎯 I am a User, I want to use it
- README.md hero —— What this tool actually does
- QUICK_START.md —— 30 minutes from clone to your first AI memo
- 09-troubleshooting.md —— Where to look when it breaks
🛠 I am a Developer, I want to modify / extend
- 01-architecture.md —— Mental model required reading
- 05-data-model.md —— v2 schema + concurrent RMW
- 07-extending.md —— Cookbook: add assets / data sources / agent roles
- 06-api.md —— REST endpoints + frontend type synchronization
- 08-deployment.md —— Caddy + CF Access + systemd
🧠 I am a Researcher, I want to understand "why it's designed this way"
- 02-agents.md —— 4 LLM roles + cross-challenge + REGIME neutral probability framework
- 03-dreaming.md —— OpenClaw-style three-phase memory consolidation
- 04-execution-paths.md —— Skill vs Web/Cron dual paths
- 11-rl-training.md —— Optuna + paper trade + training pipeline (Clarification: not GPU training)
- 12-verification.md —— Empirical data / "scientific evidence" / negative results
- 13-param-tuning-feasibility.md —— Parameter tuning feasibility diagnosis + supplementary document
- 15-path-probability.md —— Path-based probability tables: multi-window distributions + four path shapes (core reading for sell timing)
- 16-ta-analysts-experiment.md —— TradingAgents-style analyst experiment: pre-registered Gate 0/3 pass
- 17-asset-feature-sets.md —— Explicit contract for asset class feature sets (gold ≠ stock semantics)
- 18-governance-conventions.md —— Governance charter: framework/criteria/dirty data red lines/veto power (user sign-off)
- 19-telemetry-and-analytics.md —— Telemetry and data collection: anonymous installation statistics / Opt-out / Privacy commitment
- adr/ —— Architecture Decision Records (why not Claude Agent SDK, etc.)
🎨 I am a Designer / Frontend Developer, I want to modify the GUI
- 10-design-system.md —— Three token layers + typography + IA
- invest-gui/README.md —— Frontend repository structure
All Chapters
| # | Chapter | One-liner |
|---|---|---|
| 01 | Architecture Overview | 4 layers (Connectors / Agents / Core / Memory) + data flow + concurrency model |
| 02 | 4-Role Committee | Macro / Quant / Risk / CIO + cross-challenge + REGIME |
| 03 | Dreaming Memory Consolidation | Light / REM / Deep Sleep three phases, cross-session long-term memory |
| 04 | Dual Execution Paths | Skill (Claude true subagent) vs Web/Cron (DeepSeek multi-threaded) |
| 05 | Data Model | v2 schema (cash dict + holdings list) + migration + concurrency safety |
| 06 | Web API | FastAPI 40+ endpoints + Pydantic + same-origin deployment |
| 07 | Extension Guide | Adding new assets / new data sources / new agent roles |
| 08 | Production Deployment | Caddy + Cloudflare Access + systemd + sync_gui_dist |
| 09 | Troubleshooting | Where to check journal when it breaks online / SSE disconnects / sync failures |
| 10 | Design System | GUI tokens + three typography layers + IA decisions |
| 11 | RL Training / Backtest | Optuna parameter tuning + paper trade simulation + DSPy (not real ML training) |
| 12 | Verification Empirical Validation | Empirical data for 7 core claims + negative results + reproduction commands |
| 13 | Parameter Tuning Feasibility Diagnosis | 50+ hardcoded constant inventory + coupling analysis + Optuna review + sweep strategy |
| 14 | Sweep Runner | Parameter sweep toolchain |
| 15 | Path-Based Probability | 30/60/90 multi-window distributions + four path shapes + regime persistence labeling |
| 16 | TA Analyst Experiment | Two-phase signal existence experiment, 3 analysts 0/3 pass pre-registered Gate |
| 17 | Asset Feature Set Contract | Feature × asset class matrix; gold VIX semantic review; counterfactual bookkeeping |
| 18 | Governance Charter | Three principles (freeze snapshot/veto power/criteria adjudication) + single source of truth for framework + pre-merge requirement + audit log |
| 19 | Telemetry and Data Collection | One-time anonymous installation statistics + three opt-out environment variables + privacy commitment |
Architecture Decision Records (ADR)
Records of "why it was done this way," providing evidence for anyone who wants to overturn a design in the future.
| ID | Decision | Status |
|---|---|---|
| 001 | Committee retains Skill + Web/Cron dual paths | ✅ Adopted |
| 002 | Defer upgrade to Claude Agent SDK | ✅ Adopted |
| 003 | portfolio.md upgrade to v2 universal schema | ✅ Adopted |
| 004 | v1 fallback officially retired | ✅ Adopted |
| 005 | daily_report split into builder/notifier | ✅ Adopted |
| 006 | Event awareness layer + lightweight news RAG | 🚧 In progress (feature flag default off) |
| 007 | few-shot (v1-v4) retired, CIO remains zero-shot, anti-conservatism via Dreaming | ✅ Adopted |
| 008 | caution changed to lift-based scoring (touchstone validation, not reward hacking); dormant under current data; "excessive conservatism" hypothesis lacks evidence | ✅ Adopted |
| 009 | Reject TradingAgents-style analyst subagents (test_ta experiment, pre-registered Gate 0/3) | ✅ Adopted |
| 025 | Price anomaly sentinel: 10min vs daily ATR% vertical line detection, alert email first then trigger committee | ✅ Adopted |
Maintenance Rules
- This wiki is the source of "why" — specific implementation details go in code + subdirectory READMEs; this wiki only explains design intent
- Adding a major feature: must update a page (or create a new one) synchronously
- Adding a new architecture decision: must create an ADR
- Subdirectory README renamed / reorganized: wiki links must be updated accordingly
- Once an ADR is "Adopted," do not modify it; to overturn it, create a new one that supersedes it
As always: CONTRIBUTING vs Wiki division of labor — CONTRIBUTING describes "how to participate" (steady state), Wiki describes "what the system is" (living document).