Skip to content

Commit 392ef4a

Browse files
Copilotgarland3
Copilot
and
garland3
committed
Add error flow diagram documentation
- Add comprehensive visual diagram showing error flow - Documents the complete path from error to user message - Shows classification logic and error handling at each layer - 501 total lines changed across 7 files Co-authored-by: garland3 <[email protected]>
1 parent 847e374 commit 392ef4a

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

‎docs/error_flow_diagram.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Error Flow Diagram
2+
3+
## Complete Error Handling Flow
4+
5+
```
6+
┌─────────────────────────────────────────────────────────────────────┐
7+
│ USER SENDS MESSAGE │
8+
└─────────────────────────────────────────────────────────────────────┘
9+
│
10+
▼
11+
┌─────────────────────────────────────────────────────────────────────┐
12+
│ WebSocket Handler (main.py) │
13+
│ handle_chat() async function │
14+
└─────────────────────────────────────────────────────────────────────┘
15+
│
16+
▼
17+
┌─────────────────────────────────────────────────────────────────────┐
18+
│ ChatService.handle_chat_message() │
19+
│ (service.py) │
20+
└─────────────────────────────────────────────────────────────────────┘
21+
│
22+
▼
23+
┌─────────────────────────────────────────────────────────────────────┐
24+
│ ChatOrchestrator.execute() │
25+
│ (orchestrator.py) │
26+
└─────────────────────────────────────────────────────────────────────┘
27+
│
28+
▼
29+
┌─────────────────────────────────────────────────────────────────────┐
30+
│ ToolsModeRunner.run() │
31+
│ (modes/tools.py) │
32+
└─────────────────────────────────────────────────────────────────────┘
33+
│
34+
▼
35+
┌─────────────────────────────────────────────────────────────────────┐
36+
│ error_utils.safe_call_llm_with_tools() │
37+
│ (utilities/error_utils.py) │
38+
└─────────────────────────────────────────────────────────────────────┘
39+
│
40+
▼
41+
┌─────────────────────────────────────────────────────────────────────┐
42+
│ LLMCaller.call_with_tools() │
43+
│ (modules/llm/litellm_caller.py) │
44+
└─────────────────────────────────────────────────────────────────────┘
45+
│
46+
▼
47+
┌─────────────────────────────────────────────────────────────────────┐
48+
│ LiteLLM Library │
49+
│ (calls Cerebras/OpenAI/etc.) │
50+
└─────────────────────────────────────────────────────────────────────┘
51+
│
52+
▼
53+
┌─────────────┴─────────────┐
54+
│ │
55+
┌──────▼───────┐ ┌───────▼────────┐
56+
│ SUCCESS │ │ ERROR │
57+
│ (200 OK) │ │ (Rate Limit) │
58+
└──────┬───────┘ └───────┬────────┘
59+
│ │
60+
│ ▼
61+
│ ┌──────────────────────────────┐
62+
│ │ Exception: RateLimitError │
63+
│ │ "We're experiencing high │
64+
│ │ traffic right now!" │
65+
│ └──────────┬───────────────────┘
66+
│ │
67+
│ ▼
68+
│ ┌──────────────────────────────┐
69+
│ │ error_utils.classify_llm_ │
70+
│ │ error(exception) │
71+
│ │ │
72+
│ │ Returns: │
73+
│ │ - error_class: RateLimitError│
74+
│ │ - user_msg: "The AI service │
75+
│ │ is experiencing high │
76+
│ │ traffic..." │
77+
│ │ - log_msg: Full details │
78+
│ └──────────┬───────────────────┘
79+
│ │
80+
│ ▼
81+
│ ┌──────────────────────────────┐
82+
│ │ Raise RateLimitError(user_msg)│
83+
│ └──────────┬───────────────────┘
84+
│ │
85+
│ ▼
86+
┌───────────────────┴─────────────────────────┴─────────────────────┐
87+
│ Back to WebSocket Handler (main.py) │
88+
│ Exception Catching │
89+
└────────────────────────────────────────────────────────────────────┘
90+
│
91+
┌─────────────┴─────────────┐
92+
│ │
93+
┌──────▼────────┐ ┌────────▼────────────┐
94+
│ except │ │ except │
95+
│ RateLimitError │ │ LLMTimeoutError │
96+
│ │ │ LLMAuth...Error │
97+
│ Send to user: │ │ ValidationError │
98+
│ { │ │ etc. │
99+
│ type: "error",│ │ │
100+
│ message: user │ │ Send appropriate │
101+
│ friendly msg,│ │ message to user │
102+
│ error_type: │ │ │
103+
│ "rate_limit" │ │ │
104+
│ } │ │ │
105+
└───────┬────────┘ └────────┬────────────┘
106+
│ │
107+
└──────────┬───────────────┘
108+
│
109+
▼
110+
┌─────────────────────────────────────────────────────────────────────┐
111+
│ WebSocket Message Sent │
112+
│ { │
113+
│ "type": "error", │
114+
│ "message": "The AI service is experiencing high traffic...", │
115+
│ "error_type": "rate_limit" │
116+
│ } │
117+
└─────────────────────────────────────────────────────────────────────┘
118+
│
119+
▼
120+
┌─────────────────────────────────────────────────────────────────────┐
121+
│ Frontend (websocketHandlers.js) │
122+
│ │
123+
│ case 'error': │
124+
│ setIsThinking(false) │
125+
│ addMessage({ │
126+
│ role: 'system', │
127+
│ content: `Error: ${data.message}`, │
128+
│ timestamp: new Date().toISOString() │
129+
│ }) │
130+
└─────────────────────────────────────────────────────────────────────┘
131+
│
132+
▼
133+
┌─────────────────────────────────────────────────────────────────────┐
134+
│ UI DISPLAYS ERROR │
135+
│ │
136+
│ System Message: │
137+
│ "Error: The AI service is experiencing high traffic. │
138+
│ Please try again in a moment." │
139+
│ │
140+
│ [User can see the error and knows what to do] │
141+
└─────────────────────────────────────────────────────────────────────┘
142+
```
143+
144+
## Key Points
145+
146+
1. **Error Classification**: The `classify_llm_error()` function examines the exception type and message to determine the appropriate error category.
147+
148+
2. **User-Friendly Messages**: Technical errors are translated into helpful, actionable messages for users.
149+
150+
3. **Detailed Logging**: Full error details are logged for debugging purposes (not shown to users).
151+
152+
4. **Error Type Field**: The `error_type` field allows the frontend to potentially handle different error types differently in the future (e.g., automatic retry for timeouts).
153+
154+
5. **No Sensitive Data Exposure**: API keys, stack traces, and other sensitive information are never sent to the frontend.

0 commit comments

Comments
 (0)