docs/ADR/005-langgraph-streaming-chatgpt-ui.md

ADR-005: LangGraph Streaming Migration & ChatGPT-style UI

Date: 2026-05-08 Status: Accepted Deciders: Máximo López Chenlo

Context

The OncoAgent UI was a static, one-shot dashboard using agent_graph.invoke() which blocked the Gradio event loop for the entire multi-agent pipeline duration (Router → RAG → Specialist ↔ Critic → Formatter). This caused:

1. UI freezing during inference (10-60s depending on model tier and RAG complexity)
2. No conversational iteration — oncologists could not ask follow-up questions
3. Dropdown transparency bug in Gradio's dark theme making model selection unreadable
4. Monolithic CSS embedded in app.py hurting maintainability

Decision

1. Replace invoke() with stream(stream_mode="updates"): LangGraph's streaming API emits {node_name: output_dict} events as each node completes, enabling real-time progress display.

2. ChatGPT-style layout: Sidebar (session controls, KPIs, evidence tabs) + main chat area, following modern AI assistant conventions.

3. CSS module extraction: Moved all styling to ui/styles.py for separation of concerns.

4. Dropdown fix: Added 30+ explicit CSS selectors targeting Gradio's internal dropdown classes with solid backgrounds.

Consequences

Positive

• Zero perceived latency — UI updates node-by-node
• Conversational memory enables iterative clinical dialogue
• Cleaner code architecture (styles separated from logic)
• Fixed visual accessibility bug in model selector

Negative

• Streaming requires generator functions, slightly more complex handler logic
• More CSS selectors to maintain for Gradio version upgrades

Alternatives Considered

• WebSocket-based streaming: Too complex for Gradio's architecture
• Polling-based progress: Higher latency, more server load
• Streamlit migration: Would require full rewrite of all UI logic