feat: implement semantic TL;DR citations and live image support

src/core/domain/schemas.py

@@ -13,10 +13,14 @@ class SourceDocument(BaseModel):
     content: str
     metadata: dict
     score: float
+    snippet: Optional[str] = None
+    image_url: Optional[str] = None
+    citation_index: Optional[int] = None
 
 class ChatResponse(BaseModel):
     answer: str
     sources: List[SourceDocument]
+    follow_up_questions: List[str] = []
     session_id: str = "anonymous"
 
 class FeedbackRequest(BaseModel):

src/core/use_cases/rag_chat_use_case.py

@@ -131,10 +131,37 @@ Document:
 
             context_text += formatted + "\n\n"
             total_tokens += tokens
+            
+            # ── ENHANCEMENT: Extract Semantic TL;DR Highlight ──
+            doc["highlight"] = self._extract_highlight_sentence(query, content)
+            doc["image_url"] = doc.get("image_url") or metadata.get("image_url") or metadata.get("url_to_image")
+            
             filtered_sources.append(doc)
 
         return context_text, filtered_sources
 
+    def _extract_highlight_sentence(self, query: str, content: str) -> str:
+        """
+        Extracts the single most relevant sentence from the content for hoverable citations.
+        Uses a simple sentence splitter and keyword overlap for speed.
+        """
+        import re
+        sentences = re.split(r'(?<=[.!?])\s+', content)
+        if not sentences: return content[:150] + "..."
+        
+        query_terms = set(query.lower().split())
+        best_sentence = sentences[0]
+        max_overlap = -1
+        
+        for s in sentences:
+            if len(s) < 20: continue
+            overlap = len(set(s.lower().split()) & query_terms)
+            if overlap > max_overlap:
+                max_overlap = overlap
+                best_sentence = s
+        
+        return best_sentence.strip()[:250]
+
     def _extract_intents_and_translate(self, query: str) -> Dict[str, Any]:
         """
         Single LLM call: query understanding + multilingual translation.
@@ -954,6 +981,9 @@ Answer:"""
         # ── Attach citation index to each source for frontend rendering ───────
         for idx, doc in enumerate(final_sources, 1):
             doc["citation_index"] = idx
+            # Ensure snippet exists for the TL;DR hover
+            if not doc.get("snippet"):
+                doc["snippet"] = doc.get("highlight", doc.get("content", "")[:200])
 
         result = {
             "answer": answer,

src/infrastructure/adapters/duckduckgo_adapter.py

@@ -339,6 +339,8 @@ class DuckDuckGoAdapter:
             # Calculate freshness score (live results are freshest)
             freshness_score = self._calculate_freshness(published_at)
             
+            image_url = raw_result.get("image") or raw_result.get("thumbnail")
+            
             return {
                 "title": title,
                 "url": url,
@@ -346,6 +348,7 @@ class DuckDuckGoAdapter:
                 "snippet": snippet,
                 "source": source or self._extract_domain(url),
                 "published_at": published_at,
+                "image_url": image_url,
                 "source_type": "live",
                 "is_live": True,
                 "freshness_score": freshness_score,
@@ -355,6 +358,7 @@ class DuckDuckGoAdapter:
                     "url": url,
                     "source": source,
                     "published_at": published_at,
+                    "image_url": image_url,
                     "search_engine": "duckduckgo"
                 }
             }