From 9ec193ea1306c34f98b792eceeca9c0f7be195a4 Mon Sep 17 00:00:00 2001
From: Tomas Kracmar <tomas.kracmar@cqre.net>
Date: Mon, 20 Apr 2026 15:45:32 +0200
Subject: [PATCH] feat: expose LLM error reason in /api/ask response and UI

- Add llm_error field to AskResponse so users know why AI summarisation was skipped
- Show orange warning banner in frontend when LLM is not configured or call fails
- Update AskEndpoint tests to assert llm_error presence
---
 backend/frontend/index.html |  4 ++++
 backend/frontend/style.css  | 10 ++++++++++
 backend/models/api.py       |  1 +
 backend/routes/ask.py       |  8 +++++++-
 4 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/backend/frontend/index.html b/backend/frontend/index.html
index 321d1cc..0c0e79a 100644
--- a/backend/frontend/index.html
+++ b/backend/frontend/index.html
@@ -53,6 +53,7 @@
       </form>
       <template x-if="askAnswer">
         <div class="ask-result">
+          <div x-show="askLlmError" class="ask-error" x-text="askLlmError"></div>
           <div class="ask-answer" x-html="askAnswerHtml"></div>
           <template x-if="askEvents.length">
             <div class="ask-events">
@@ -245,6 +246,7 @@
         askAnswerHtml: '',
         askEvents: [],
         askLlmUsed: false,
+        askLlmError: '',
 
         async initApp() {
           await this.initAuth();
@@ -501,6 +503,7 @@
             this.askAnswerHtml = this._mdToHtml(body.answer);
             this.askEvents = body.events || [];
             this.askLlmUsed = body.llm_used;
+            this.askLlmError = body.llm_error || '';
           } catch (err) {
             this.askAnswer = 'Sorry, something went wrong: ' + (err.message || 'Unknown error');
             this.askAnswerHtml = this.askAnswer;
@@ -515,6 +518,7 @@
           this.askAnswerHtml = '';
           this.askEvents = [];
           this.askLlmUsed = false;
+          this.askLlmError = '';
         },
 
         _mdToHtml(text) {
diff --git a/backend/frontend/style.css b/backend/frontend/style.css
index 4e78fdd..1b18cd0 100644
--- a/backend/frontend/style.css
+++ b/backend/frontend/style.css
@@ -418,6 +418,16 @@ input {
   font-size: 13px;
 }
 
+.ask-error {
+  background: rgba(249, 115, 22, 0.1);
+  border: 1px solid rgba(249, 115, 22, 0.3);
+  border-radius: 8px;
+  padding: 10px 14px;
+  color: #fdba74;
+  font-size: 14px;
+  margin-bottom: 10px;
+}
+
 .ask-events {
   margin-bottom: 14px;
 }
diff --git a/backend/models/api.py b/backend/models/api.py
index b22e679..e7ff83a 100644
--- a/backend/models/api.py
+++ b/backend/models/api.py
@@ -92,3 +92,4 @@ class AskResponse(BaseModel):
     events: list[AskEventRef]
     query_info: dict
     llm_used: bool
+    llm_error: str | None = None
diff --git a/backend/routes/ask.py b/backend/routes/ask.py
index 59e78ff..a459e03 100644
--- a/backend/routes/ask.py
+++ b/backend/routes/ask.py
@@ -272,16 +272,21 @@ async def ask_question(body: AskRequest, user: dict = Depends(require_auth)):
             events=[],
             query_info={"entity": entity, "start": start, "end": end, "event_count": 0},
             llm_used=False,
+            llm_error="LLM not used — no events found." if not LLM_API_KEY else None,
         )
 
     # Try LLM summarisation
     answer = ""
     llm_used = False
-    if LLM_API_KEY:
+    llm_error = None
+    if not LLM_API_KEY:
+        llm_error = "LLM_API_KEY is not configured. Set it in your .env to enable AI narrative summarisation."
+    else:
         try:
             answer = await _call_llm(question, events)
             llm_used = True
         except Exception as exc:
+            llm_error = f"LLM call failed: {exc}"
             logger.warning("LLM call failed, falling back to structured summary", error=str(exc))
 
     # Fallback: structured summary if LLM unavailable or failed
@@ -315,4 +320,5 @@ async def ask_question(body: AskRequest, user: dict = Depends(require_auth)):
             "mongo_query": json.dumps(query, default=str),
         },
         llm_used=llm_used,
+        llm_error=llm_error,
     )