TradingAgents/agent_os/DESIGN.md

AgentOS: Visual Observability Design

1. The Literal Graph Visualization (Agent Map)

The agent map is a directed graph (DAG) representing the LangGraph workflow in real-time.

Implementation Strategy

• Frontend: Powered by React Flow. Nodes are added and connected as WebSocket events arrive.
• Node Data Contract:
  • node_id: Unique identifier for the graph node.
  • parent_node_id: For building edges in real-time.
  • metrics: { "tokens_in": int, "tokens_out": int, "latency_ms": float, "model": str }.
• Interactivity: Clicking a node opens an Inspector Drawer showing:
  • LLM Metrics: Model name, Request/Response tokens, Latency (ms).
  • Payload: Raw JSON response and rationale.

Pause & Restart (Next Phase TODO)

• Interrupts: Use LangGraph's interrupt_before features to halt execution at specific nodes (e.g., trader_node).
• Control API: POST /api/run/{run_id}/resume to signal the graph to continue.

---

2. The "Top 3" Metrics Consensus

Synthetic consensus between Economist (Efficiency/Risk) and UI Designer (Clarity/Action):

1. Trailing 30-Day Sharpe Ratio (Risk-Adjusted Efficiency)

   • Economist: "Absolute P&L is vanity; we need to know the quality of the returns."
   • Display: Large gauge showing trading efficiency.

2. Current Market Regime & Beta (Macro Alignment)

   • Economist: "Signals if we are riding the trend or fighting it."
   • Display: Status badge (BULL/BEAR) + Beta value relative to S&P 500.

3. Real-Time Drawdown & 1-Day VaR (Capital Preservation)

   • UI Designer: "The 'Red Alert' metric. It must be visible if we are losing capital."
   • Display: Percentage bar showing distance from the All-Time High.

---

3. Tech Stack

• Backend: FastAPI, LangChain, Supabase (Postgres).
• Frontend: React, Chakra UI, React Flow, Axios.
• Protocol: REST for triggers, WebSockets for live streaming.
• Network:
  • Backend: 127.0.0.1:8088 (to avoid macOS system conflicts)
  • Frontend: localhost:5173