feat: implement chat with note backend endpoint and register chat router

src/api/chat_routes.py

@@ -0,0 +1,76 @@
+"""
+Chat routes — Document-specific Q&A powered by Groq.
+"""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, Field
+
+from src.auth.dependencies import get_current_user
+from src.db.models import User
+from src.summarization.note_generator import NoteGenerator
+from src.utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+router = APIRouter(tags=["Chat"])
+
+
+# ─── Schemas ──────────────────────────────────────────────────────────
+
+class ChatMessage(BaseModel):
+    role: str = Field(..., description="Either 'user' or 'assistant'")
+    content: str = Field(..., description="Message content")
+
+
+class ChatRequest(BaseModel):
+    note_content: str = Field(
+        ...,
+        description="The full text of the note to use as context",
+    )
+    question: str = Field(
+        ...,
+        min_length=1,
+        description="The user's question about the note",
+    )
+    history: Optional[List[ChatMessage]] = Field(
+        default=None,
+        description="Previous conversation turns for multi-turn context",
+    )
+
+
+class ChatResponse(BaseModel):
+    answer: str = Field(..., description="AI-generated answer")
+
+
+# ─── Endpoint ─────────────────────────────────────────────────────────
+
+@router.post("/chat/note", response_model=ChatResponse)
+async def chat_with_note(
+    request: ChatRequest,
+    current_user: User = Depends(get_current_user),
+):
+    """Ask a question about a specific note. Answers are grounded in the note content."""
+    logger.info(
+        "Chat request from user %s — question length: %d, context length: %d",
+        current_user.id,
+        len(request.question),
+        len(request.note_content),
+    )
+
+    if not request.note_content.strip():
+        raise HTTPException(status_code=400, detail="Note content cannot be empty.")
+
+    note_gen = NoteGenerator()
+
+    history_dicts = None
+    if request.history:
+        history_dicts = [msg.model_dump() for msg in request.history]
+
+    answer = note_gen.chat_with_note(
+        note_content=request.note_content,
+        question=request.question,
+        history=history_dicts,
+    )
+
+    return ChatResponse(answer=answer)

src/api/main.py

@@ -8,6 +8,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from src.api.auth_routes import router as auth_router
 from src.api.notes_routes import router as notes_router
 from src.api.recommendation_routes import router as recommendation_router
+from src.api.chat_routes import router as chat_router
 from src.utils.logger import setup_logger
 
 logger = setup_logger(__name__)
@@ -36,6 +37,7 @@ app.add_middleware(
 app.include_router(notes_router)
 app.include_router(recommendation_router)
 app.include_router(auth_router)
+app.include_router(chat_router)
 
 @app.get("/")
 def read_root():

src/summarization/note_generator.py

@@ -1,340 +1,403 @@
-import json
-import os
-import re
-from typing import Dict, List, Optional
-
-from pydantic import ValidationError
-from groq import Groq
-
-from ..utils.logger import setup_logger
-from .schemas import SummarySchema
-from .segmenter import TranscriptSegmenter
-
-
-logger = setup_logger(__name__)
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# PROMPT TEMPLATES
-# ─────────────────────────────────────────────────────────────────────────────
-
-_SUMMARY_SYSTEM = """
-You are an expert educational content analyst and structured note-taking specialist.
-Transform raw video transcripts into clean, structured chronological JSON summaries.
-
-LANGUAGE RULE — CRITICAL, NEVER VIOLATE:
-- Detect the primary language of the transcript.
-- Every content field (title, summary, segments, conclusion) MUST be written entirely in that SAME detected language.
-- Do NOT mix languages. Arabic transcript -> everything in Arabic.
-- Only the "detected_language" field itself is stated in English (e.g. "Arabic").
-
-TIMELINE RULES — STRICTLY ENFORCED:
-- Divide the transcript into chronological segments that follow its natural progression.
-- Produce a MINIMUM of 3 and a MAXIMUM of 7 segments.
-- Each segment MUST cover a distinct phase or theme; do NOT repeat the same topic.
-- Segments must be ordered chronologically as they appear in the transcript.
-- Each segment must include:
-  * title: a short descriptive title
-  * summary: concise summary of that section (2-3 sentences)
-  * key_insight: the single most important takeaway from that section
-  * why_it_matters: brief explanation of value/importance (1-2 sentences)
-
-TOPICS RULE:
-- Extract the actual topics discussed in the video dynamically.
-- Topics should be specific and descriptive (e.g. "Python", "Machine Learning", "Neural Networks").
-- Do NOT use generic fixed categories.
-
-CRITICAL: RETURN A JSON OBJECT EXACTLY MATCHING THIS STRUCTURE.
-DO NOT CHANGE, OMIT, OR RENAME ANY KEYS.
-{
-    "title": "Inferred video title in transcript language",
-    "detected_language": "English (or Arabic, etc.)",
-    "summary": "Concise overall summary (3-5 sentences)",
-    "segments": [
-        {
-            "title": "Segment title",
-            "summary": "What this section covers (2-3 sentences)",
-            "key_insight": "Most important point from this section",
-            "why_it_matters": "Why this is valuable (1-2 sentences)"
-        }
-    ],
-    "conclusion": "Final overall takeaway / closing conclusion",
-    "topics": ["Topic1", "Topic2", "Topic3"]
-}
-
-OUTPUT: Return ONLY a valid JSON object. No markdown fences, no extra text.
-""".strip()
-
-_SUMMARY_USER = """
-Video Title: {video_title}
-
-TRANSCRIPT:
-{transcript}
-
-Analyze thoroughly. Detect the language.
-Divide the content into 3-7 chronological segments.
-For each segment provide: title, summary, key_insight, why_it_matters.
-Return ONLY the exact JSON structure requested.
-""".strip()
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# LANGUAGE LABELS (simplified)
-# ─────────────────────────────────────────────────────────────────────────────
-
-_LABELS = {
-    "Arabic": {
-        "source":     "المصدر",
-        "duration":   "المدة",
-        "summary":    "الملخص العام",
-        "timeline":   "التسلسل الزمني",
-        "insight":    "أهم نقطة",
-        "why":        "لماذا يهم؟",
-        "conclusion": "الخلاصة",
-    },
-    "English": {
-        "source":     "Source",
-        "duration":   "Duration",
-        "summary":    "Overall Summary",
-        "timeline":   "Timeline",
-        "insight":    "Key Insight",
-        "why":        "Why It Matters",
-        "conclusion": "Conclusion",
-    },
-}
-
-def _labels(language: str) -> dict:
-    return _LABELS.get(language, _LABELS["English"])
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# TOKEN UTILITIES
-# ─────────────────────────────────────────────────────────────────────────────
-
-_CHUNK_TARGET_TOKENS = 2500
-
-def _estimate_tokens(text: str) -> int:
-    """
-    Lightweight token estimation using a word-count heuristic.
-
-    Production logs show that Groq's tokenizer produces ~2.5 tokens per
-    whitespace-delimited word for Arabic / mixed-script transcripts.
-    Using 2.5× as a conservative multiplier to avoid underestimation.
-    """
-    word_count = len(text.split())
-    return int(word_count * 2.5)
-
-
-def _split_into_chunks(text: str, target_tokens: int = _CHUNK_TARGET_TOKENS) -> List[str]:
-    """
-    Split text into chunks of approximately `target_tokens` tokens each.
-
-    Splits on sentence boundaries (period + space, newline) to avoid
-    cutting mid-sentence. Falls back to word-level splitting if no
-    sentence boundaries are found within a chunk.
-    """
-    # Split into sentences (on ". " or newline)
-    sentences = re.split(r'(?<=[.!?])\s+|\n+', text)
-    sentences = [s.strip() for s in sentences if s.strip()]
-
-    chunks: List[str] = []
-    current_chunk: List[str] = []
-    current_tokens = 0
-
-    for sentence in sentences:
-        sentence_tokens = _estimate_tokens(sentence)
-
-        # If a single sentence exceeds the target, split by words
-        if sentence_tokens > target_tokens:
-            # Flush current chunk first
-            if current_chunk:
-                chunks.append(" ".join(current_chunk))
-                current_chunk = []
-                current_tokens = 0
-
-            words = sentence.split()
-            word_buffer: List[str] = []
-            buffer_tokens = 0
-            for word in words:
-                wt = _estimate_tokens(word)
-                if buffer_tokens + wt > target_tokens and word_buffer:
-                    chunks.append(" ".join(word_buffer))
-                    word_buffer = [word]
-                    buffer_tokens = wt
-                else:
-                    word_buffer.append(word)
-                    buffer_tokens += wt
-            if word_buffer:
-                chunks.append(" ".join(word_buffer))
-            continue
-
-        if current_tokens + sentence_tokens > target_tokens and current_chunk:
-            chunks.append(" ".join(current_chunk))
-            current_chunk = [sentence]
-            current_tokens = sentence_tokens
-        else:
-            current_chunk.append(sentence)
-            current_tokens += sentence_tokens
-
-    # Don't forget the last chunk
-    if current_chunk:
-        chunks.append(" ".join(current_chunk))
-
-    return chunks
-
-
-# ─────────────────────────────────────────────────────────────────────────────
-# NOTE GENERATOR
-# ─────────────────────────────────────────────────────────────────────────────
-
-class NoteGenerator:
-    """Generates structured study notes using Groq (Llama-3.3-70b-versatile)."""
-
-    def __init__(self):
-        self.api_key = os.environ.get("GROQ_API_KEY", "").strip()
-        self.client = Groq(api_key=self.api_key) if self.api_key else None
-        self.model_id = "llama-3.3-70b-versatile"
-        logger.info(f"🚀 NoteGenerator v4.0 initialized — model: {self.model_id}")
-
-    def _chat(self, system: str, user: str, max_tokens: int = 4096) -> Optional[str]:
-        if not self.client:
-            return None
-        try:
-            response = self.client.chat.completions.create(
-                model=self.model_id,
-                max_tokens=max_tokens,
-                temperature=0.3,
-                response_format={"type": "json_object"},
-                messages=[
-                    {"role": "system", "content": system},
-                    {"role": "user",   "content": user},
-                ],
-            )
-            return response.choices[0].message.content
-        except Exception as e:
-            logger.error(f"❌ Groq API call failed: {e}")
-            return None
-
-    def _get_error_json(self, error_msg: str) -> Dict:
-        return {
-            "title": "Error in Generation",
-            "detected_language": "English",
-            "summary": f"Could not generate notes: {error_msg}",
-            "segments": [],
-            "conclusion": "",
-            "topics": [],
-        }
-
-    def generateSummary(self, transcript_text: str, video_title: str) -> Dict:
-        """Generate structured JSON summary from transcript."""
-        if not self.client:
-            return self._get_error_json("Groq API Key missing.")
-
-        logger.info(f"📝 Summary generation started via {self.model_id}")
-        user_prompt = _SUMMARY_USER.format(
-            video_title=video_title,
-            transcript=transcript_text[:30000],
-        )
-
-        raw = self._chat(_SUMMARY_SYSTEM, user_prompt, max_tokens=4096)
-        if raw is None:
-            return self._get_error_json("Groq API call failed.")
-
-        try:
-            data = json.loads(raw)
-            validated = SummarySchema(**data)
-            return validated.model_dump()
-        except (json.JSONDecodeError, ValidationError) as e:
-            logger.error(f"❌ Schema validation failed: {e}")
-            return self._get_error_json(f"Validation Error: {str(e)}")
-
-    def format_notes_to_markdown(self, json_notes: Dict) -> str:
-        """Convert JSON notes to clean Markdown — Summary → Timeline → Conclusion."""
-        lang = json_notes.get("detected_language", "English")
-        L = _labels(lang)
-        lines: list[str] = []
-
-        def add(text: str = ""):
-            lines.append(text)
-
-        def blank():
-            lines.append("")
-
-        def divider():
-            lines.append("")
-            lines.append("---")
-            lines.append("")
-
-        # ── OVERALL SUMMARY ──
-        summary = json_notes.get("summary", "")
-        if summary:
-            add(f"## 📋 {L['summary']}")
-            blank()
-            add(summary)
-            divider()
-
-        # ── TIMELINE ──
-        segments = json_notes.get("segments", [])
-        if segments:
-            add(f"## 🕐 {L['timeline']}")
-            blank()
-            for i, seg in enumerate(segments, start=1):
-                s_title   = seg.get("title", "")   if isinstance(seg, dict) else seg.title
-                s_summary = seg.get("summary", "")  if isinstance(seg, dict) else seg.summary
-                s_insight = seg.get("key_insight", "") if isinstance(seg, dict) else seg.key_insight
-                s_why     = seg.get("why_it_matters", "") if isinstance(seg, dict) else seg.why_it_matters
-
-                add(f"### {i}. {s_title}")
-                blank()
-                add(s_summary)
-                blank()
-                if s_insight:
-                    add(f"> **💎 {L['insight']}:** {s_insight}")
-                    blank()
-                if s_why:
-                    add(f"> **{L['why']}** {s_why}")
-                    blank()
-            divider()
-
-        # ── CONCLUSION ──
-        conclusion = json_notes.get("conclusion", "")
-        if conclusion:
-            add(f"## 🔖 {L['conclusion']}")
-            blank()
-            add(f"> {conclusion}")
-            blank()
-
-        return "\n".join(lines)
-
-    def format_final_notes(
-        self,
-        notes: str,
-        video_title: str,
-        video_url: str,
-        duration: int,
-        detected_language: str = "English",
-    ) -> str:
-        """
-        Wrap the formatted Markdown body with Source + Duration header.
-        """
-        L = _labels(detected_language)
-
-        if duration and duration > 0:
-            hours   = duration // 3600
-            minutes = (duration % 3600) // 60
-            secs    = duration % 60
-            if hours > 0:
-                duration_str = f"{hours}:{minutes:02d}:{secs:02d}"
-            else:
-                duration_str = f"{minutes:02d}:{secs:02d}"
-        else:
-            duration_str = "N/A (Auto-generated)"
-
-        header = (
-            f"# {video_title}\n\n"
-            f"---\n\n"
-            f"> **{L['source']}:** {video_url}  \n"
-            f"> **{L['duration']}:** {duration_str}\n\n"
-            f"---\n\n"
-        )
-        return header + notes
+import json
+import os
+import re
+from typing import Dict, List, Optional
+
+from pydantic import ValidationError
+from groq import Groq
+
+from ..utils.logger import setup_logger
+from .schemas import SummarySchema
+from .segmenter import TranscriptSegmenter
+
+
+logger = setup_logger(__name__)
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PROMPT TEMPLATES
+# ─────────────────────────────────────────────────────────────────────────────
+
+_SUMMARY_SYSTEM = """
+You are an expert educational content analyst and structured note-taking specialist.
+Transform raw video transcripts into clean, structured chronological JSON summaries.
+
+LANGUAGE RULE — CRITICAL, NEVER VIOLATE:
+- Detect the primary language of the transcript.
+- Every content field (title, summary, segments, conclusion) MUST be written entirely in that SAME detected language.
+- Do NOT mix languages. Arabic transcript -> everything in Arabic.
+- Only the "detected_language" field itself is stated in English (e.g. "Arabic").
+
+TIMELINE RULES — STRICTLY ENFORCED:
+- Divide the transcript into chronological segments that follow its natural progression.
+- Produce a MINIMUM of 3 and a MAXIMUM of 7 segments.
+- Each segment MUST cover a distinct phase or theme; do NOT repeat the same topic.
+- Segments must be ordered chronologically as they appear in the transcript.
+- Each segment must include:
+  * title: a short descriptive title
+  * summary: concise summary of that section (2-3 sentences)
+  * key_insight: the single most important takeaway from that section
+  * why_it_matters: brief explanation of value/importance (1-2 sentences)
+
+TOPICS RULE:
+- Extract the actual topics discussed in the video dynamically.
+- Topics should be specific and descriptive (e.g. "Python", "Machine Learning", "Neural Networks").
+- Do NOT use generic fixed categories.
+
+CRITICAL: RETURN A JSON OBJECT EXACTLY MATCHING THIS STRUCTURE.
+DO NOT CHANGE, OMIT, OR RENAME ANY KEYS.
+{
+    "title": "Inferred video title in transcript language",
+    "detected_language": "English (or Arabic, etc.)",
+    "summary": "Concise overall summary (3-5 sentences)",
+    "segments": [
+        {
+            "title": "Segment title",
+            "summary": "What this section covers (2-3 sentences)",
+            "key_insight": "Most important point from this section",
+            "why_it_matters": "Why this is valuable (1-2 sentences)"
+        }
+    ],
+    "conclusion": "Final overall takeaway / closing conclusion",
+    "topics": ["Topic1", "Topic2", "Topic3"]
+}
+
+OUTPUT: Return ONLY a valid JSON object. No markdown fences, no extra text.
+""".strip()
+
+_SUMMARY_USER = """
+Video Title: {video_title}
+
+TRANSCRIPT:
+{transcript}
+
+Analyze thoroughly. Detect the language.
+Divide the content into 3-7 chronological segments.
+For each segment provide: title, summary, key_insight, why_it_matters.
+Return ONLY the exact JSON structure requested.
+""".strip()
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# LANGUAGE LABELS (simplified)
+# ─────────────────────────────────────────────────────────────────────────────
+
+_LABELS = {
+    "Arabic": {
+        "source":     "المصدر",
+        "duration":   "المدة",
+        "summary":    "الملخص العام",
+        "timeline":   "التسلسل الزمني",
+        "insight":    "أهم نقطة",
+        "why":        "لماذا يهم؟",
+        "conclusion": "الخلاصة",
+    },
+    "English": {
+        "source":     "Source",
+        "duration":   "Duration",
+        "summary":    "Overall Summary",
+        "timeline":   "Timeline",
+        "insight":    "Key Insight",
+        "why":        "Why It Matters",
+        "conclusion": "Conclusion",
+    },
+}
+
+def _labels(language: str) -> dict:
+    return _LABELS.get(language, _LABELS["English"])
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# TOKEN UTILITIES
+# ─────────────────────────────────────────────────────────────────────────────
+
+_CHUNK_TARGET_TOKENS = 2500
+
+def _estimate_tokens(text: str) -> int:
+    """
+    Lightweight token estimation using a word-count heuristic.
+
+    Production logs show that Groq's tokenizer produces ~2.5 tokens per
+    whitespace-delimited word for Arabic / mixed-script transcripts.
+    Using 2.5× as a conservative multiplier to avoid underestimation.
+    """
+    word_count = len(text.split())
+    return int(word_count * 2.5)
+
+
+def _split_into_chunks(text: str, target_tokens: int = _CHUNK_TARGET_TOKENS) -> List[str]:
+    """
+    Split text into chunks of approximately `target_tokens` tokens each.
+
+    Splits on sentence boundaries (period + space, newline) to avoid
+    cutting mid-sentence. Falls back to word-level splitting if no
+    sentence boundaries are found within a chunk.
+    """
+    # Split into sentences (on ". " or newline)
+    sentences = re.split(r'(?<=[.!?])\s+|\n+', text)
+    sentences = [s.strip() for s in sentences if s.strip()]
+
+    chunks: List[str] = []
+    current_chunk: List[str] = []
+    current_tokens = 0
+
+    for sentence in sentences:
+        sentence_tokens = _estimate_tokens(sentence)
+
+        # If a single sentence exceeds the target, split by words
+        if sentence_tokens > target_tokens:
+            # Flush current chunk first
+            if current_chunk:
+                chunks.append(" ".join(current_chunk))
+                current_chunk = []
+                current_tokens = 0
+
+            words = sentence.split()
+            word_buffer: List[str] = []
+            buffer_tokens = 0
+            for word in words:
+                wt = _estimate_tokens(word)
+                if buffer_tokens + wt > target_tokens and word_buffer:
+                    chunks.append(" ".join(word_buffer))
+                    word_buffer = [word]
+                    buffer_tokens = wt
+                else:
+                    word_buffer.append(word)
+                    buffer_tokens += wt
+            if word_buffer:
+                chunks.append(" ".join(word_buffer))
+            continue
+
+        if current_tokens + sentence_tokens > target_tokens and current_chunk:
+            chunks.append(" ".join(current_chunk))
+            current_chunk = [sentence]
+            current_tokens = sentence_tokens
+        else:
+            current_chunk.append(sentence)
+            current_tokens += sentence_tokens
+
+    # Don't forget the last chunk
+    if current_chunk:
+        chunks.append(" ".join(current_chunk))
+
+    return chunks
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# NOTE GENERATOR
+# ─────────────────────────────────────────────────────────────────────────────
+
+class NoteGenerator:
+    """Generates structured study notes using Groq (Llama-3.3-70b-versatile)."""
+
+    def __init__(self):
+        self.api_key = os.environ.get("GROQ_API_KEY", "").strip()
+        self.client = Groq(api_key=self.api_key) if self.api_key else None
+        self.model_id = "llama-3.3-70b-versatile"
+        logger.info(f"🚀 NoteGenerator v4.0 initialized — model: {self.model_id}")
+
+    def _chat(self, system: str, user: str, max_tokens: int = 4096) -> Optional[str]:
+        if not self.client:
+            return None
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model_id,
+                max_tokens=max_tokens,
+                temperature=0.3,
+                response_format={"type": "json_object"},
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user",   "content": user},
+                ],
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            logger.error(f"❌ Groq API call failed: {e}")
+            return None
+
+    def _get_error_json(self, error_msg: str) -> Dict:
+        return {
+            "title": "Error in Generation",
+            "detected_language": "English",
+            "summary": f"Could not generate notes: {error_msg}",
+            "segments": [],
+            "conclusion": "",
+            "topics": [],
+        }
+
+    def generateSummary(self, transcript_text: str, video_title: str) -> Dict:
+        """Generate structured JSON summary from transcript."""
+        if not self.client:
+            return self._get_error_json("Groq API Key missing.")
+
+        logger.info(f"📝 Summary generation started via {self.model_id}")
+        user_prompt = _SUMMARY_USER.format(
+            video_title=video_title,
+            transcript=transcript_text[:30000],
+        )
+
+        raw = self._chat(_SUMMARY_SYSTEM, user_prompt, max_tokens=4096)
+        if raw is None:
+            return self._get_error_json("Groq API call failed.")
+
+        try:
+            data = json.loads(raw)
+            validated = SummarySchema(**data)
+            return validated.model_dump()
+        except (json.JSONDecodeError, ValidationError) as e:
+            logger.error(f"❌ Schema validation failed: {e}")
+            return self._get_error_json(f"Validation Error: {str(e)}")
+
+    def format_notes_to_markdown(self, json_notes: Dict) -> str:
+        """Convert JSON notes to clean Markdown — Summary → Timeline → Conclusion."""
+        lang = json_notes.get("detected_language", "English")
+        L = _labels(lang)
+        lines: list[str] = []
+
+        def add(text: str = ""):
+            lines.append(text)
+
+        def blank():
+            lines.append("")
+
+        def divider():
+            lines.append("")
+            lines.append("---")
+            lines.append("")
+
+        # ── OVERALL SUMMARY ──
+        summary = json_notes.get("summary", "")
+        if summary:
+            add(f"## 📋 {L['summary']}")
+            blank()
+            add(summary)
+            divider()
+
+        # ── TIMELINE ──
+        segments = json_notes.get("segments", [])
+        if segments:
+            add(f"## 🕐 {L['timeline']}")
+            blank()
+            for i, seg in enumerate(segments, start=1):
+                s_title   = seg.get("title", "")   if isinstance(seg, dict) else seg.title
+                s_summary = seg.get("summary", "")  if isinstance(seg, dict) else seg.summary
+                s_insight = seg.get("key_insight", "") if isinstance(seg, dict) else seg.key_insight
+                s_why     = seg.get("why_it_matters", "") if isinstance(seg, dict) else seg.why_it_matters
+
+                add(f"### {i}. {s_title}")
+                blank()
+                add(s_summary)
+                blank()
+                if s_insight:
+                    add(f"> **💎 {L['insight']}:** {s_insight}")
+                    blank()
+                if s_why:
+                    add(f"> **{L['why']}** {s_why}")
+                    blank()
+            divider()
+
+        # ── CONCLUSION ──
+        conclusion = json_notes.get("conclusion", "")
+        if conclusion:
+            add(f"## 🔖 {L['conclusion']}")
+            blank()
+            add(f"> {conclusion}")
+            blank()
+
+        return "\n".join(lines)
+
+    def format_final_notes(
+        self,
+        notes: str,
+        video_title: str,
+        video_url: str,
+        duration: int,
+        detected_language: str = "English",
+    ) -> str:
+        """
+        Wrap the formatted Markdown body with Source + Duration header.
+        """
+        L = _labels(detected_language)
+
+        if duration and duration > 0:
+            hours   = duration // 3600
+            minutes = (duration % 3600) // 60
+            secs    = duration % 60
+            if hours > 0:
+                duration_str = f"{hours}:{minutes:02d}:{secs:02d}"
+            else:
+                duration_str = f"{minutes:02d}:{secs:02d}"
+        else:
+            duration_str = "N/A (Auto-generated)"
+
+        header = (
+            f"# {video_title}\n\n"
+            f"---\n\n"
+            f"> **{L['source']}:** {video_url}  \n"
+            f"> **{L['duration']}:** {duration_str}\n\n"
+            f"---\n\n"
+        )
+        return header + notes
+
+    # ─────────────────────────────────────────────────────────────────────
+    # CHAT WITH NOTE (Document-Specific Q&A)
+    # ─────────────────────────────────────────────────────────────────────
+
+    _CHAT_SYSTEM = (
+        "You are an AI assistant helping the user understand a video note. "
+        "Answer the user's question strictly using the provided context below. "
+        "If the answer is not in the context, politely inform the user that "
+        "the video does not mention it. Do not hallucinate or invent information. "
+        "Keep your answers clear, concise, and helpful. "
+        "If the context is in Arabic, reply in Arabic. Match the language of the context."
+    )
+
+    _CHAT_CONTEXT_LIMIT = 25_000  # characters — safe for Groq free-tier TPM
+
+    def chat_with_note(
+        self,
+        note_content: str,
+        question: str,
+        history: list[dict] | None = None,
+    ) -> str:
+        """Answer a user question grounded in the provided note content."""
+        if not self.client:
+            return "AI service is not configured. Please set the GROQ_API_KEY."
+
+        truncated_context = note_content[: self._CHAT_CONTEXT_LIMIT]
+
+        messages: list[dict] = [
+            {"role": "system", "content": self._CHAT_SYSTEM},
+            {
+                "role": "user",
+                "content": (
+                    f"--- VIDEO NOTE CONTEXT ---\n"
+                    f"{truncated_context}\n"
+                    f"--- END OF CONTEXT ---"
+                ),
+            },
+        ]
+
+        # Append conversation history (if any)
+        if history:
+            for msg in history:
+                role = msg.get("role", "user")
+                content = msg.get("content", "")
+                if role in ("user", "assistant") and content:
+                    messages.append({"role": role, "content": content})
+
+        # Append the current question
+        messages.append({"role": "user", "content": question})
+
+        try:
+            response = self.client.chat.completions.create(
+                model=self.model_id,
+                max_tokens=1024,
+                temperature=0.3,
+                messages=messages,
+            )
+            answer = response.choices[0].message.content
+            return answer.strip() if answer else "I couldn't generate a response."
+        except Exception as e:
+            logger.error(f"❌ Chat API call failed: {e}")
+            return f"Sorry, something went wrong: {str(e)}"