webapp — Full-Stack Web Application

🎯 Why This Module Exists

The CLI is powerful for developers but inaccessible to non-technical users and lacks persistence. The web application adds three critical capabilities: (1) Visual workflow building — drag-and-drop agent composition using React Flow, where each agent is a node and edges define execution order; (2) Persistent configuration — saved flows and execution history in SQLite via SQLAlchemy ORM, so users can iterate on strategies without re-entering parameters; and (3) Real-time feedback — Server-Sent Events (SSE) streaming shows agent-by-agent progress as the pipeline executes, with each agent's status, ticker, and analysis pushed to the browser as it completes. Without the web app, users would need to edit Python code to change agent configurations, pass complex CLI arguments for every run, and every execution would be ephemeral with no history.

🚶 Step-by-Step Narrated Walkthrough

Follow a single user running a hedge fund workflow through the web UI from start to finish:

1. Canvas Setup — The user drags Warren Buffett and Ben Graham agent nodes onto the React Flow canvas, then connects both to a Portfolio Tracking & Performance Metrics" href="../backtesting_doc/portfolio/index.html">Portfolio Manager node with edges.
2. Configuration — The user selects tickers (AAPL, GOOGL), date range, initial cash ($100k), and chooses GPT-4o as the model. These are captured by custom React hooks.
3. Request Dispatch — Clicking "Run" triggers a POST to /hedge-fund/run with a HedgeFundRequest payload containing graph_nodes, graph_edges, tickers, and model config.
4. API Key Hydration — The route handler checks if API keys were provided in the request. If not, it loads them from the database via ApiKeyService.
5. Orchestration" href="../core_doc/graph/index.html">Graph Construction — create_graph() in services/graph.py maps React Flow node IDs to agent functions using ANALYST_CONFIG. It strips 6-character suffixes (extract_base_agent_key) to match unique canvas IDs to base agent names.
6. Edge Wiring — The service iterates edges, detects direct analyst-to-portfolio-manager connections, and automatically interposes a Risk Manager node. Entry-point agents (no incoming edges) are connected to start_node.
7. SSE Stream Opens — The route returns a StreamingResponse. A progress handler is registered that pushes ProgressUpdateEvent objects to an asyncio.Queue.
8. Async Execution — run_graph_async() wraps the synchronous graph.invoke() in loop.run_in_executor() so it runs in a thread pool without blocking the event loop.
9. Progress Streaming — As each agent completes, it calls progress.update_status(). The registered handler enqueues a ProgressUpdateEvent. The event generator dequeues it and yields an SSE-formatted string to the browser.
10. Client Disconnect Detection — A wait_for_disconnect() coroutine monitors for http.disconnect messages, allowing cleanup if the user navigates away mid-run.
11. Completion — After all agents finish, parse_hedge_fund_response() extracts the final JSON. A CompleteEvent is pushed to the SSE stream with trading recommendations.
12. Frontend Update — The React app parses each SSE event, updates agent card states (pending, running, complete), and renders the final portfolio allocation table.

React Flow to StateGraph Translation

The Problem: The React Flow canvas produces a flat list of nodes (with unique IDs like warren_buffett_a1b2c3) and edges (source/target pairs). This must be translated into a LangGraph StateGraph with proper entry points, agent wiring, and mandatory risk management steps.

The Approach: The create_graph() function performs a multi-pass translation: (1) Extract base agent keys by stripping 6-char suffixes. (2) Register agent nodes, tracking portfolio managers separately. (3) For each portfolio manager, create a paired risk manager with a matching suffix. (4) Scan edges: direct analyst-to-portfolio-manager connections are rerouted through the risk manager. (5) Nodes with no incoming agent edges become entry points connected to start_node. (6) Portfolio managers connect to END.

Why This Algorithm: A single-pass approach would require lookahead to handle the risk manager interposition. The multi-pass design keeps each concern isolated: node registration, edge wiring, and entry/exit point detection are independent passes over the data.

flowchart TD
    A["React Flow nodes + edges"] --> B["Pass 1: Extract base agent keys\nstrip 6-char suffixes"]
    B --> C["Pass 2: Register agent nodes\nseparate portfolio managers"]
    C --> D["Pass 3: Create risk manager\nfor each portfolio manager"]
    D --> E["Pass 4: Wire edges\ninterpose risk managers"]
    E --> F["Pass 5: Connect entry points\nto start_node"]
    F --> G["Pass 6: Connect portfolio\nmanagers to END"]
    G --> H["Compiled StateGraph"]

Hot Paths

The most performance-sensitive code paths in the web application:

• Graph construction (create_graph): O(N + E) where N = nodes, E = edges. Multiple passes over the data but each is linear. Typically under 1ms for realistic graph sizes (5-15 agents).
• SSE event serialization: Each ProgressUpdateEvent is serialized to JSON and formatted as an SSE string. Throughput is limited by agent execution speed, not serialization (<1ms per event).
• Thread pool dispatch: run_in_executor(None, ...) uses the default thread pool. Each concurrent run occupies one thread for the duration of graph execution (30s-5min depending on agent count and LLM latency).

Resource Usage

• Memory: Each active run holds a full AgentState in memory (~5-20 MB depending on number of tickers and agents). The SQLite database grows linearly with saved flows and execution history.
• Concurrency: FastAPI handles concurrent requests via asyncio, but graph execution is thread-bound. The default thread pool (typically 40 threads) limits concurrent workflow runs.
• Startup: Base.metadata.create_all() runs on startup (~10ms). Ollama status check is async and non-blocking. CORS middleware adds negligible overhead per request.