new app

src/app.py

@@ -0,0 +1,17 @@
+"""Main entry point for the PDF Explainer app."""
+
+import gradio as gr
+from processors.pdf_processor import PDFProcessor
+from ui_components.interface import build_interface
+from dotenv import load_dotenv
+
+load_dotenv()
+
+def main():
+    pdf_processor = PDFProcessor()
+    demo = build_interface(pdf_processor.process_pdf)
+    return demo
+
+if __name__ == "__main__":
+    demo = main()
+    demo.launch()

src/processors/audio_processor.py

@@ -0,0 +1,24 @@
+"""Audio generation functionality."""
+
+import gradio as gr
+
+class AudioProcessor:
+    """Handles audio generation operations."""
+    def generate_audio(self, explanation_text):
+        """Generate TTS audio for explanations."""
+        if not explanation_text or explanation_text.strip() == "":
+            raise gr.Error("No explanations available to convert to audio. Please generate explanations first.")
+        try:
+            from .generate_tts_audio import generate_tts_audio
+            clean_text = explanation_text.strip()
+            if len(clean_text) > 1000:
+                sentences = clean_text[:950].split('.')
+                if len(sentences) > 1:
+                    clean_text = '.'.join(sentences[:-1]) + '.'
+                else:
+                    clean_text = clean_text[:950]
+                clean_text += " [Text has been truncated for audio generation]"
+            audio_result = generate_tts_audio(clean_text, None)
+            return audio_result, gr.update(visible=True)
+        except Exception as e:
+            raise gr.Error(f"Error generating audio: {str(e)}")

src/processors/explanation_processor.py

@@ -0,0 +1,18 @@
+"""Explanation generation functionality."""
+
+from pdf_text_extractor import PDFTextExtractor
+
+class ExplanationProcessor:
+    """Handles explanation generation operations."""
+    def __init__(self):
+        self.extractor = PDFTextExtractor()
+
+    def generate_explanations(self, extracted_text):
+        """Generate explanations for extracted text."""
+        if not extracted_text or extracted_text.strip() == "":
+            return "No text available to explain. Please extract text from a PDF first."
+        try:
+            explanations = self.extractor.generate_explanations(extracted_text)
+            return explanations
+        except Exception as e:
+            return f"Error generating explanations: {str(e)}"

src/processors/generate_tts_audio.py

@@ -0,0 +1,111 @@
+def generate_tts_audio(text_input: str, audio_prompt_input, progress=None):
+    import os
+    import requests
+    import tempfile
+    import soundfile as sf
+    import numpy as np
+    import gradio as gr
+    
+    GENERATE_AUDIO_ENDPOINT = os.getenv("GENERATE_AUDIO_ENDPOINT", "YOUR-MODAL-ENDPOINT-URL/generate_audio")
+    GENERATE_WITH_FILE_ENDPOINT = os.getenv("GENERATE_WITH_FILE_ENDPOINT", "YOUR-MODAL-ENDPOINT-URL/generate_with_file")
+    
+    if not text_input or len(text_input.strip()) == 0:
+        raise gr.Error("Please enter some text to synthesize.")
+    
+    if progress: progress(0.1, desc="Preparing request...")
+    
+    try:
+        if audio_prompt_input is None:
+            if progress: progress(0.3, desc="Sending request to API...")
+            payload = {"text": text_input}
+            response = requests.post(
+                GENERATE_AUDIO_ENDPOINT,
+                json=payload,
+                headers={"Content-Type": "application/json"},
+                timeout=120,
+                stream=True
+            )
+            if response.status_code != 200:
+                raise gr.Error(f"API Error: {response.status_code} - {response.text}")
+            
+            if progress: progress(0.6, desc="Streaming audio response...")
+            
+            # Get content length if available for progress tracking
+            content_length = response.headers.get('content-length')
+            if content_length:
+                content_length = int(content_length)
+            
+            bytes_downloaded = 0
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as temp_file:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        temp_file.write(chunk)
+                        bytes_downloaded += len(chunk)
+                        
+                        # Update progress based on bytes downloaded
+                        if content_length and progress:
+                            download_progress = min(0.3, (bytes_downloaded / content_length) * 0.3)
+                            progress(0.6 + download_progress, desc=f"Downloading audio... ({bytes_downloaded // 1024}KB)")
+                        elif progress:
+                            # If no content length, just show bytes downloaded
+                            progress(0.6, desc=f"Downloading audio... ({bytes_downloaded // 1024}KB)")
+                            
+                temp_path = temp_file.name
+                
+            if progress: progress(0.9, desc="Processing audio...")
+            audio_data, sample_rate = sf.read(temp_path)
+            os.unlink(temp_path)
+            if progress: progress(1.0, desc="Complete!")
+            return (sample_rate, audio_data)
+            
+        else:
+            if progress: progress(0.3, desc="Preparing voice prompt...")
+            files = {'text': (None, text_input)}
+            with open(audio_prompt_input, 'rb') as f:
+                audio_content = f.read()
+            files['voice_prompt'] = ('voice_prompt.wav', audio_content, 'audio/wav')
+            
+            if progress: progress(0.5, desc="Sending request with voice cloning...")
+            response = requests.post(
+                GENERATE_WITH_FILE_ENDPOINT,
+                files=files,
+                timeout=180,
+                stream=True
+            )
+            if response.status_code != 200:
+                raise gr.Error(f"API Error: {response.status_code} - {response.text}")
+            
+            if progress: progress(0.8, desc="Streaming cloned voice response...")
+            
+            # Get content length if available for progress tracking
+            content_length = response.headers.get('content-length')
+            if content_length:
+                content_length = int(content_length)
+            
+            bytes_downloaded = 0
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as temp_file:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        temp_file.write(chunk)
+                        bytes_downloaded += len(chunk)
+                        
+                        # Update progress based on bytes downloaded for voice cloning
+                        if content_length and progress:
+                            download_progress = min(0.15, (bytes_downloaded / content_length) * 0.15)
+                            progress(0.8 + download_progress, desc=f"Downloading cloned audio... ({bytes_downloaded // 1024}KB)")
+                        elif progress:
+                            progress(0.8, desc=f"Downloading cloned audio... ({bytes_downloaded // 1024}KB)")
+                            
+                temp_path = temp_file.name
+                
+            audio_data, sample_rate = sf.read(temp_path)
+            os.unlink(temp_path)
+            if progress: progress(1.0, desc="Voice cloning complete!")
+            return (sample_rate, audio_data)
+            
+    except requests.exceptions.Timeout:
+        raise gr.Error("Request timed out. The API might be under heavy load. Please try again.")
+    except requests.exceptions.ConnectionError:
+        raise gr.Error("Unable to connect to the API. Please check if the endpoint URL is correct.")
+    except Exception as e:
+        raise gr.Error(f"Error generating audio: {str(e)}")

src/processors/pdf_processor.py

@@ -0,0 +1,69 @@
+"""PDF processing functionality."""
+
+import gradio as gr
+from .pdf_text_extractor import PDFTextExtractor
+
+
+class PDFProcessor:
+    """Handles PDF processing operations."""
+    
+    def __init__(self):
+        self.extractor = PDFTextExtractor()
+    
+    def process_pdf(self, pdf_file):
+        """Process PDF and extract text, then explanations, then audio, updating UI at each step."""
+        if pdf_file is None:
+            yield "", "No PDF uploaded", "", None, gr.update(visible=False)
+            return
+        
+        try:
+            # Step 1: Extract text
+            # Show "Extracting text..." message
+            yield "", gr.update(value="Extracting text..."), "", None, gr.update(visible=False)
+            extracted_text, status, images_data = self.extractor.extract_text_from_pdf(pdf_file)
+            
+            if not extracted_text or extracted_text.strip() == "":
+                yield extracted_text, status, "No text available to explain.", None, gr.update(visible=False)
+                return
+            
+            # Show extracted text immediately, explanations/audio loading
+            yield extracted_text, status, gr.update(value="Generating explanations..."), None, gr.update(visible=False)
+            
+            # Step 2: Generate explanations
+            try:
+                explanations = self.extractor.generate_explanations(extracted_text)
+                
+                # Show explanations immediately, update status for audio loading
+                yield extracted_text, gr.update(value="Generating audio..."), explanations, None, gr.update(visible=False)
+                
+                # Step 3: Generate audio
+                try:
+                    from .generate_tts_audio import generate_tts_audio
+                    
+                    # Clean up the text for better TTS
+                    clean_text = explanations.strip()
+                    
+                    # Limit text length for TTS (assuming 1000 character limit)
+                    if len(clean_text) > 1000:
+                        sentences = clean_text[:950].split('.')
+                        if len(sentences) > 1:
+                            clean_text = '.'.join(sentences[:-1]) + '.'
+                        else:
+                            clean_text = clean_text[:950]
+                        clean_text += " [Text has been truncated for audio generation]"
+                    
+                    audio_result = generate_tts_audio(clean_text, None)
+                    
+                    # Show everything, update status to complete
+                    yield extracted_text, gr.update(value="All steps complete!"), explanations, audio_result, gr.update(visible=True)
+                    
+                except Exception as audio_error:
+                    # Show explanations, update status with audio error
+                    yield extracted_text, gr.update(value=f"Audio generation failed: {str(audio_error)}"), explanations, None, gr.update(visible=False)
+                    
+            except Exception as explanation_error:
+                # Show extracted text, but indicate explanation error
+                yield extracted_text, status, f"Error generating explanations: {str(explanation_error)}", None, gr.update(visible=False)
+            
+        except Exception as e:
+            yield "", f"Error processing PDF: {str(e)}", "", None, gr.update(visible=False)

src/processors/pdf_text_extractor.py

@@ -0,0 +1,287 @@
+import base64
+import os
+from typing import Optional, Tuple, List, Dict, Any
+from mistralai import Mistral
+from utils.text_explainer import TextExplainer
+
+class PDFTextExtractor:
+    """PDF text extraction using Mistral AI OCR."""
+    
+    def __init__(self):
+        """Initialize the PDF text extractor with Mistral AI client."""
+        self.api_key = os.environ.get("MISTRAL_API_KEY")
+        if not self.api_key:
+            raise ValueError("MISTRAL_API_KEY environment variable is required")
+        self.client = Mistral(api_key=self.api_key)
+        self.text_explainer = TextExplainer()
+    
+    def encode_pdf(self, pdf_path: str) -> Optional[str]:
+        """
+        Encode the PDF file to base64.
+        
+        Args:
+            pdf_path: Path to the PDF file
+            
+        Returns:
+            Base64 encoded string or None if error
+        """
+        try:
+            with open(pdf_path, "rb") as pdf_file:
+                return base64.b64encode(pdf_file.read()).decode('utf-8')
+        except FileNotFoundError:
+            print(f"Error: The file {pdf_path} was not found.")
+            return None
+        except Exception as e:
+            print(f"Error encoding PDF: {e}")
+            return None
+    
+    def extract_text_from_pdf(self, pdf_file) -> Tuple[str, str, List[Dict[str, Any]]]:
+        """
+        Extract text and images from uploaded PDF using Mistral AI OCR.
+        
+        Args:
+            pdf_file: Gradio file object
+            
+        Returns:
+            Tuple of (extracted_text, status_message, images_data)
+        """
+        if pdf_file is None:
+            return "", "Please upload a PDF file.", []
+        
+        try:
+            # Get the file path from Gradio file object
+            pdf_path = pdf_file.name if hasattr(pdf_file, 'name') else pdf_file
+            
+            # Encode PDF to base64
+            base64_pdf = self.encode_pdf(pdf_path)
+            if base64_pdf is None:
+                return "", "Failed to encode PDF file.", []
+            
+            # Process with Mistral OCR
+            print(f"🔄 Processing PDF with Mistral OCR...")
+            ocr_response = self.client.ocr.process(
+                model="mistral-ocr-latest",
+                document={
+                    "type": "document_url",
+                    "document_url": f"data:application/pdf;base64,{base64_pdf}" 
+                },
+                include_image_base64=True
+            )
+            
+            # Enhanced debugging and response parsing
+            print("🔍 Analyzing OCR Response Structure...")
+            print(f"  Type: {type(ocr_response)}")
+            print(f"  String representation: {str(ocr_response)[:500]}...")
+            
+            # Check if it's a simple object with attributes
+            if hasattr(ocr_response, '__dict__'):
+                print(f"  Object attributes: {list(ocr_response.__dict__.keys())}")
+                for key, value in ocr_response.__dict__.items():
+                    print(f"    {key}: {type(value)} = {str(value)[:100]}...")
+            
+            # Check if it has commonly expected attributes
+            common_attrs = ['text', 'content', 'result', 'data', 'output', 'extracted_text', 'ocr_text', 'choices', 'message']
+            for attr in common_attrs:
+                if hasattr(ocr_response, attr):
+                    value = getattr(ocr_response, attr)
+                    print(f"  Has '{attr}': {type(value)} = {str(value)[:100]}...")
+            
+            # Check if it's iterable but not a string
+            try:
+                if hasattr(ocr_response, '__iter__') and not isinstance(ocr_response, str):
+                    print(f"  Iterable with {len(list(ocr_response))} items")
+                    for i, item in enumerate(ocr_response):
+                        if i < 3:  # Show first 3 items
+                            print(f"    Item {i}: {type(item)} = {str(item)[:100]}...")
+            except Exception as e:
+                print(f"  Error checking iteration: {e}")
+            
+            # Advanced text extraction with multiple strategies
+            extracted_text = ""
+            extraction_method = "none"
+            extracted_images = []
+            
+            # Strategy 1: Mistral OCR specific - pages with markdown content and images
+            if hasattr(ocr_response, 'pages') and ocr_response.pages:
+                pages = ocr_response.pages
+                if isinstance(pages, list) and len(pages) > 0:
+                    page_texts = []
+                    
+                    for i, page in enumerate(pages):
+                        # Extract text
+                        if hasattr(page, 'markdown') and page.markdown:
+                            page_texts.append(page.markdown)
+                            print(f"✅ Found text in page {i} markdown: {len(page.markdown)} characters")
+                        
+                        # Extract images
+                        if hasattr(page, 'images') and page.images:
+                            for j, img in enumerate(page.images):
+                                image_data = {
+                                    'page': i,
+                                    'image_id': f"img-{i}-{j}",
+                                    'top_left_x': getattr(img, 'top_left_x', 0),
+                                    'top_left_y': getattr(img, 'top_left_y', 0),
+                                    'bottom_right_x': getattr(img, 'bottom_right_x', 0),
+                                    'bottom_right_y': getattr(img, 'bottom_right_y', 0),
+                                    'base64': getattr(img, 'image_base64', '')
+                                }
+                                extracted_images.append(image_data)
+                                print(f"✅ Found image in page {i}, image {j}: coordinates ({image_data['top_left_x']}, {image_data['top_left_y']}) to ({image_data['bottom_right_x']}, {image_data['bottom_right_y']})")
+                    
+                    if page_texts:
+                        extracted_text = "\n\n".join(page_texts)
+                        extraction_method = f"pages_markdown_{len(page_texts)}_pages"
+            
+            # Try to extract images from other response structures if no images found yet
+            if not extracted_images:
+                # Check if response has images attribute directly
+                if hasattr(ocr_response, 'images') and ocr_response.images:
+                    for j, img in enumerate(ocr_response.images):
+                        image_data = {
+                            'page': 0,
+                            'image_id': getattr(img, 'id', f"img-{j}"),
+                            'top_left_x': getattr(img, 'top_left_x', 0),
+                            'top_left_y': getattr(img, 'top_left_y', 0),
+                            'bottom_right_x': getattr(img, 'bottom_right_x', 0),
+                            'bottom_right_y': getattr(img, 'bottom_right_y', 0),
+                            'base64': getattr(img, 'image_base64', '')
+                        }
+                        extracted_images.append(image_data)
+                        print(f"✅ Found image {j}: coordinates ({image_data['top_left_x']}, {image_data['top_left_y']}) to ({image_data['bottom_right_x']}, {image_data['bottom_right_y']})")
+            
+            # Continue with fallback strategies for text extraction
+            if not extracted_text:
+                # Strategy 2: Direct text attribute (fallback)
+                if hasattr(ocr_response, 'text') and ocr_response.text:
+                    extracted_text = str(ocr_response.text)
+                    extraction_method = "direct_text_attribute"
+                
+                # Strategy 3: Content attribute (fallback)
+                elif hasattr(ocr_response, 'content') and ocr_response.content:
+                    content = ocr_response.content
+                    if isinstance(content, str):
+                        extracted_text = content
+                        extraction_method = "content_attribute_string"
+                    elif hasattr(content, 'text'):
+                        extracted_text = str(content.text)
+                        extraction_method = "content_text_attribute"
+                    else:
+                        extracted_text = str(content)
+                        extraction_method = "content_attribute_converted"
+                
+                # Strategy 4: Result attribute (fallback)
+                elif hasattr(ocr_response, 'result'):
+                    result = ocr_response.result
+                    if isinstance(result, str):
+                        extracted_text = result
+                        extraction_method = "result_string"
+                    elif hasattr(result, 'text'):
+                        extracted_text = str(result.text)
+                        extraction_method = "result_text_attribute"
+                    elif isinstance(result, dict) and 'text' in result:
+                        extracted_text = str(result['text'])
+                        extraction_method = "result_dict_text"
+                    else:
+                        extracted_text = str(result)
+                        extraction_method = "result_converted"
+                
+                # Strategy 5: Choices attribute (ChatGPT-style response - fallback)
+                elif hasattr(ocr_response, 'choices') and ocr_response.choices:
+                    choices = ocr_response.choices
+                    if isinstance(choices, list) and len(choices) > 0:
+                        choice = choices[0]
+                        if hasattr(choice, 'message') and hasattr(choice.message, 'content'):
+                            extracted_text = str(choice.message.content)
+                            extraction_method = "choices_message_content"
+                        elif hasattr(choice, 'text'):
+                            extracted_text = str(choice.text)
+                            extraction_method = "choices_text"
+                        else:
+                            extracted_text = str(choice)
+                            extraction_method = "choices_converted"
+                
+                # Strategy 6: Dict-like access (fallback)
+                elif hasattr(ocr_response, 'get') or isinstance(ocr_response, dict):
+                    for key in ['text', 'content', 'result', 'extracted_text', 'ocr_text', 'output']:
+                        if hasattr(ocr_response, 'get'):
+                            value = ocr_response.get(key)
+                        else:
+                            value = ocr_response.get(key) if isinstance(ocr_response, dict) else None
+                        
+                        if value:
+                            extracted_text = str(value)
+                            extraction_method = f"dict_key_{key}"
+                            break
+                
+                # Strategy 7: Inspect all attributes for string-like content (fallback)
+                elif hasattr(ocr_response, '__dict__'):
+                    for key, value in ocr_response.__dict__.items():
+                        if isinstance(value, str) and len(value) > 20:  # Likely text content
+                            extracted_text = value
+                            extraction_method = f"attribute_{key}"
+                            break
+                        elif hasattr(value, 'text') and isinstance(value.text, str):
+                            extracted_text = str(value.text)
+                            extraction_method = f"nested_text_in_{key}"
+                            break
+                
+                # Strategy 8: Convert entire response to string if it seems to contain text (fallback)
+                if not extracted_text:
+                    response_str = str(ocr_response)
+                    if len(response_str) > 50 and not response_str.startswith('<'):  # Not an object reference
+                        extracted_text = response_str
+                        extraction_method = "full_response_string"
+            
+            print(f"🎯 Extraction method used: {extraction_method}")
+            print(f"📏 Extracted text length: {len(extracted_text)} characters")
+            print(f"🖼️ Extracted images: {len(extracted_images)}")
+            
+            if extracted_text:
+                status = f"✅ Successfully extracted text from PDF ({len(extracted_text)} characters)"
+                if extracted_images:
+                    status += f" and {len(extracted_images)} image(s)"
+            else:
+                extracted_text = "No text could be extracted from this PDF."
+                status = "⚠️ OCR completed but no text was found in response."
+                if extracted_images:
+                    status = f"✅ Successfully extracted {len(extracted_images)} image(s) from PDF, but no text was found."
+                print(f"❌ No extractable text found in OCR response")
+            
+            return extracted_text, status, extracted_images
+            
+        except Exception as e:
+            error_msg = f"Error processing PDF: {str(e)}"
+            print(error_msg)
+            return "", f"❌ {error_msg}", []
+    
+    def generate_explanations(self, extracted_text: str) -> str:
+        """
+        Generate explanations for the extracted text sections.
+        
+        Args:
+            extracted_text: The extracted text from PDF
+            
+        Returns:
+            Formatted explanations for all sections
+        """
+        try:
+            if not extracted_text or extracted_text.strip() == "":
+                return "No text available to explain."
+            
+            if extracted_text.startswith("No text could be extracted"):
+                return "Cannot generate explanations - no text was extracted from the PDF."
+            
+            print("🤖 Generating explanations for extracted text...")
+            explained_sections = self.text_explainer.explain_all_sections(extracted_text)
+            
+            if not explained_sections:
+                return "No sections found to explain in the extracted text."
+            
+            formatted_explanations = self.text_explainer.format_explanations_for_display(explained_sections)
+            return formatted_explanations
+            
+        except Exception as e:
+            error_msg = f"Error generating explanations: {str(e)}"
+            print(error_msg)
+            return f"❌ {error_msg}"
+

src/ui_components/interface.py

@@ -0,0 +1,57 @@
+"""UI component and layout for the PDF Explainer app."""
+
+import gradio as gr
+from gradio_pdf import PDF
+from .styles import get_fullscreen_css
+
+def build_interface(process_pdf_fn):
+    """Builds and returns the Gradio interface."""
+    with gr.Blocks(title="🔍 PDF Text Extractor", theme=gr.themes.Soft()) as demo:
+        gr.HTML(get_fullscreen_css())
+        gr.Markdown("# 🔍 PDF Text Extractor")
+        gr.Markdown("Upload a PDF on the left to automatically extract and view text on the right.")
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=1):
+                gr.Markdown("### 📄 PDF Document")
+                pdf_input = PDF(
+                    label="Upload and View PDF",
+                    height=600,
+                    interactive=True
+                )
+                status_output = gr.Textbox(
+                    label="Status",
+                    lines=2,
+                    placeholder="Upload a PDF to see status...",
+                    interactive=False
+                )
+            with gr.Column(scale=1):
+                gr.Markdown("### 📝 Extracted Content")
+                with gr.Tabs():
+                    with gr.TabItem("Extracted Text"):
+                        text_output = gr.Textbox(
+                            label="Extracted Text",
+                            lines=20,
+                            placeholder="Upload a PDF to automatically extract text...",
+                            show_copy_button=True,
+                            interactive=False
+                        )
+                    with gr.TabItem("Explanation Script"):
+                        explanation_output = gr.Textbox(
+                            label="Generated Explanation Script",
+                            lines=15,
+                            placeholder="Explanations will be automatically generated after text extraction...",
+                            show_copy_button=True,
+                            interactive=False
+                        )
+                gr.Markdown("### 🔊 Audio Generation")
+                audio_output = gr.Audio(
+                    label="Generated Explanation Audio",
+                    interactive=False,
+                    visible=False
+                )
+        pdf_input.upload(
+            fn=process_pdf_fn,
+            inputs=[pdf_input],
+            outputs=[text_output, status_output, explanation_output, audio_output, audio_output]
+        )
+    return demo

src/ui_components/styles.py

@@ -0,0 +1,19 @@
+"""CSS styles for the PDF Explainer application."""
+
+def get_fullscreen_css():
+    """Return CSS for fullscreen layout."""
+    return """
+    <style>
+    html, body, #root, .gradio-container {
+        height: 100% !important;
+        width: 100% !important;
+        margin: 0 !important;
+        padding: 0 !important;
+    }
+    .gradio-container {
+        max-width: 100vw !important;
+        min-height: 100vh !important;
+        box-sizing: border-box;
+    }
+    </style>
+    """

src/utils/text_explainer.py

@@ -0,0 +1,341 @@
+"""
+Text Explanation utilities using Mistral AI.
+Splits text by markdown headings and generates contextual explanations for each section.
+Maintains chat history to provide coherent explanations that build upon previous sections.
+"""
+
+import os
+import re
+from typing import List, Dict, Tuple, Optional
+from mistralai import Mistral
+
+
+class TextExplainer:
+    """Generate explanations for text sections using Mistral AI."""
+    
+    def __init__(self):
+        """Initialize the text explainer with Mistral AI client."""
+        self.api_key = os.environ.get("MISTRAL_API_KEY")
+        if not self.api_key:
+            raise ValueError("MISTRAL_API_KEY environment variable is required")
+        self.client = Mistral(api_key=self.api_key)
+        self.chat_history = []
+
+    def get_topic(self, text: str) -> Optional[str]:
+        """
+        Extract the main topic from the text using Mistral AI with structured output.
+        
+        Args:
+            text: Input text to analyze
+            
+        Returns:
+            Main topic as a string or None if not found
+        """
+        try:
+            # Define the JSON schema for structured output
+            topic_schema = {
+                "type": "json_schema",
+                "json_schema": {
+                    "schema": {
+                        "type": "object",
+                        "properties": {
+                            "main_topic": {
+                                "type": "string",
+                                "title": "Main Topic",
+                                "description": "The primary / general topic or subject of the text"
+                            },
+                        },
+                        "required": ["main_topic"],
+                        "additionalProperties": False
+                    },
+                    "name": "topic_extraction",
+                    "strict": True
+                }
+            }
+            
+            response = self.client.chat.complete(
+                model="ministral-8b-2410",  # Using a more recent model that supports structured output
+                messages=[
+                    {
+                        "role": "system",
+                        "content": "You are an expert in summarizing texts. Extract the main topic from the provided text."
+                    },
+                    {
+                        "role": "user",
+                        "content": f"Analyze this text and extract the main topic:\n\n{text[:2000]}..."  # Limit to first 2000 characters for performance
+                    }
+                ],
+                temperature=0.3,  # Lower temperature for more consistent structured output
+                max_tokens=200,
+                response_format=topic_schema
+            )
+            
+            if hasattr(response, 'choices') and response.choices:
+                # Parse the structured JSON response
+                import json
+                try:
+                    topic_data = json.loads(response.choices[0].message.content)
+                    main_topic = topic_data.get("main_topic", "").strip()
+                    confidence = topic_data.get("confidence", 0.0)
+                    secondary_topics = topic_data.get("secondary_topics", [])
+                    
+                    # Log the structured output for debugging
+                    print(f"📊 Topic extraction - Main: '{main_topic}', Confidence: {confidence:.2f}")
+                    if secondary_topics:
+                        print(f"🔍 Secondary topics: {', '.join(secondary_topics)}")
+                    
+                    return main_topic if main_topic else None
+                except json.JSONDecodeError as json_err:
+                    print(f"Error parsing JSON response: {json_err}")
+                    # Fallback to raw content if JSON parsing fails
+                    return response.choices[0].message.content.strip()
+            return None
+        except Exception as e:
+            print(f"Error extracting topic: {str(e)}")
+            return None
+
+    def split_text_by_headings(self, text: str) -> List[Dict[str, str]]:
+        """
+        Split text into sections based on markdown headings.
+        
+        Args:
+            text: Input text with markdown headings
+            
+        Returns:
+            List of dictionaries with 'heading' and 'content' keys
+        """
+        if not text:
+            return []
+        
+        # Split by markdown headings (# ## ### etc.)
+        sections = []
+        
+        # Regex to find headings and their content
+        # Matches: # Heading, ## Heading, ### Heading, etc.
+        heading_pattern = r'^(#{1,6})\s+(.+?)$'
+        
+        lines = text.split('\n')
+        current_heading = None
+        current_content = []
+        current_level = 0
+        
+        for line in lines:
+            heading_match = re.match(heading_pattern, line.strip())
+            
+            if heading_match:
+                # Save previous section if it exists
+                if current_heading and current_content:
+                    content_text = '\n'.join(current_content).strip()
+                    if content_text:  # Only add if there's actual content
+                        sections.append({
+                            'heading': current_heading,
+                            'content': content_text,
+                            'level': current_level
+                        })
+                
+                # Start new section
+                level = len(heading_match.group(1))  # Count the # characters
+                current_heading = heading_match.group(2).strip()
+                current_level = level
+                current_content = []
+            else:
+                # Add line to current content if we have a heading
+                if current_heading is not None:
+                    current_content.append(line)
+        
+        # Don't forget the last section
+        if current_heading and current_content:
+            content_text = '\n'.join(current_content).strip()
+            if content_text:
+                sections.append({
+                    'heading': current_heading,
+                    'content': content_text,
+                    'level': current_level
+                })
+        
+        # If no headings found, treat entire text as one section
+        if not sections and text.strip():
+            sections.append({
+                'heading': 'Document Content',
+                'content': text.strip(),
+                'level': 1
+            })
+        return sections
+
+    def generate_explanation(self, topic: str, heading: str, content: str, section_number: int = 1, total_sections: int = 1) -> str:
+        """
+        Generate an explanation for a text section using Mistral AI with chat history context.
+        
+        Args:
+            topic: General topic of the document
+            heading: Section heading
+            content: Section content
+            section_number: Current section number (for context)
+            total_sections: Total number of sections (for context)
+            
+        Returns:
+            Generated explanation in simple terms
+        """
+        try:
+            # Build the current user message
+            prompt = f"""
+            **Section {section_number} of {total_sections}**
+            **Section Heading:** {heading}
+
+            **Section Content:**
+            {content}
+
+            **Your Explanation:**"""
+
+            # If this is the first section, initialize with system prompt
+            if section_number == 1:
+                system_prompt = f"""You are an expert teacher who explains complex topics in simple, easy-to-understand terms.
+
+                I will give you sections of text with their headings on the topic of "{topic}", and I want you to explain what each section is about in simple language, by breaking down any complex concepts or terminology. You should also explain why this information might be important or useful, use examples or analogies when helpful, and keep the explanation engaging and educational.
+
+                Make your explanation clear enough for someone without prior knowledge of the topic to understand. As you explain each section, consider how it relates to the previous sections you've already explained to provide coherent, contextual explanations throughout the document.
+
+                Do not mention anything far irrelevant from the topic of "{topic}". Do not repeat information unnecessarily, but build on previous explanations to create a comprehensive understanding of the topic. Avoid using the term 'section' and use the actual section heading instead. No need to mention the section number in your explanation.
+                """
+                
+                # Initialize chat history with system message
+                self.chat_history = [
+                    {
+                        "role": "system",
+                        "content": system_prompt
+                    }
+                ]
+
+            # Check if content is too small (less than 200 characters)
+            if len(content) < 200:
+                print(f"📋 Skipping API call for short content in '{heading}' ({len(content)} chars < 200)")
+                # Add the user prompt to chat history for context in subsequent queries
+                self.chat_history.append({
+                    "role": "user",
+                    "content": prompt
+                })
+                # Return a simple message indicating the content was too short
+                return f"This section contains minimal content ({len(content)} characters). The information has been noted for context in subsequent explanations."
+
+            # Add the current user message to chat history
+            self.chat_history.append({
+                "role": "user",
+                "content": prompt
+            })
+
+            # Call Mistral AI for explanation with full chat history
+            response = self.client.chat.complete(
+                model="mistral-small-2503",
+                messages=self.chat_history,
+                temperature=0.7,  # Some creativity but still focused
+                # max_tokens=1000   # Reasonable explanation length
+            )
+            
+            # Extract the explanation from response
+            if hasattr(response, 'choices') and response.choices:
+                explanation = response.choices[0].message.content
+                
+                # Add the assistant's response to chat history
+                self.chat_history.append({
+                    "role": "assistant",
+                    "content": explanation
+                })
+                
+                return explanation.strip()
+            else:
+                return f"Could not generate explanation for section: {heading}"
+        
+        except Exception as e:
+            print(f"Error generating explanation for '{heading}': {str(e)}")
+            return f"Error generating explanation for this section: {str(e)}"
+        
+    def explain_all_sections(self, text: str) -> List[Dict[str, str]]:
+        """
+        Split text by headings and generate explanations for all sections with chat history context.
+        
+        Args:
+            text: Input text with markdown headings
+            
+        Returns:
+            List of dictionaries with 'heading', 'content', 'explanation', and 'level' keys
+        """
+        sections = self.split_text_by_headings(text)
+        
+        if not sections:
+            return []
+        
+        print(f"🔍 Found {len(sections)} sections to explain...")
+        
+        # Extract the main topic from the text
+        print("🎯 Extracting main topic...")
+        topic = self.get_topic(text)
+        if topic:
+            print(f"📋 Main topic identified: {topic}")
+        else:
+            topic = "General Content"  # Fallback topic
+            print("⚠️ Could not identify main topic, using fallback")
+        
+        # Reset chat history for new document
+        self.chat_history = []
+        
+        explained_sections = []
+        
+        for i, section in enumerate(sections, 1):
+            print(f"📝 Generating explanation for section {i}/{len(sections)}: {section['heading'][:50]}...")
+            
+            # Pass topic, section content, and context information
+            explanation = self.generate_explanation(
+                topic,
+                section['heading'], 
+                section['content'], 
+                section_number=i, 
+                total_sections=len(sections)
+            )
+            
+            explained_sections.append({
+                'heading': section['heading'],
+                'content': section['content'],
+                'explanation': explanation,
+                'level': section['level']
+            })
+        
+        print(f"✅ Generated explanations for all {len(explained_sections)} sections")
+        return explained_sections
+    
+    def reset_chat_history(self):
+        """Reset the chat history for a new document or conversation."""
+        self.chat_history = []
+    
+    def get_chat_history(self) -> List[Dict[str, str]]:
+        """Get the current chat history for debugging purposes."""
+        return self.chat_history.copy()
+    
+    def get_chat_history_summary(self) -> str:
+        """Get a summary of the current chat history."""
+        if not self.chat_history:
+            return "No chat history available."
+        
+        summary = f"Chat history contains {len(self.chat_history)} messages:\n"
+        for i, message in enumerate(self.chat_history, 1):
+            role = message['role']
+            content_preview = message['content'][:100] + "..." if len(message['content']) > 100 else message['content']
+            summary += f"{i}. {role.upper()}: {content_preview}\n"
+        
+        return summary
+
+    def format_explanations_for_display(self, explained_sections: List[Dict[str, str]]) -> str:
+        """
+        Concatenate only the explanations from all sections for display, filtering out placeholder explanations for minimal content.
+        Args:
+            explained_sections: List of sections with explanations
+        Returns:
+            Concatenated explanations as a single string
+        """
+        if not explained_sections:
+            return "No sections found to explain."
+        skip_phrase = "This section contains minimal content"
+        return "\n\n".join(
+            section['explanation']
+            for section in explained_sections
+            if section.get('explanation') and not section['explanation'].strip().startswith(skip_phrase)
+        )