Update app.py

app.py

@@ -13,19 +13,63 @@ import time
 import atexit
 from requests.exceptions import RequestException
 
-# Direct import of Mistral client and its exception.
-# An ImportError will now occur at script start if the library is not installed.
-from mistralai import Mistral
-from mistralai.exceptions import MistralAPIException
+# --- Mistral Client Import & Placeholder for graceful degradation ---
+_MISTRAL_CLIENT_INSTALLED = False
+try:
+    from mistralai import Mistral
+    from mistralai.exceptions import MistralAPIException
+    _MISTRAL_CLIENT_INSTALLED = True
+except ImportError:
+    print(
+        "Warning: Mistral AI client library ('mistralai') not found. "
+        "Please install it with 'pip install mistralai' to enable AI analysis features. "
+        "The application will launch, but API calls will fail."
+    )
+    # Define placeholder classes to prevent NameErrors and provide clear messages
+    class MistralAPIException(Exception):
+        """A placeholder for mistralai.exceptions.MistralAPIException."""
+        def __init__(self, message: str, status_code: Optional[int] = None):
+            super().__init__(message)
+            self.message = message
+            self.status_code = status_code or 500
+        def __str__(self):
+            return f"MistralAPIException (Status: {self.status_code}): {self.message}"
+
+    class _DummyMistralChatClient:
+        """Placeholder for Mistral client's chat interface."""
+        def complete(self, *args, **kwargs):
+            raise MistralAPIException(
+                "Mistral AI chat client is unavailable. "
+                "Please install 'mistralai' with 'pip install mistralai'.",
+                status_code=500
+            )
+    class _DummyMistralFilesClient:
+        """Placeholder for Mistral client's files interface."""
+        def upload(self, *args, **kwargs):
+            raise MistralAPIException(
+                "Mistral AI files client is unavailable. "
+                "Please install 'mistralai' with 'pip install mistralai'.",
+                status_code=500
+            )
+    class Mistral:
+        """A placeholder for the Mistral client if the library is not installed."""
+        def __init__(self, *args, **kwargs):
+            pass # Constructor doesn't need to raise here, methods will.
+        @property
+        def chat(self):
+            return _DummyMistralChatClient()
+        @property
+        def files(self):
+            return _DummyMistralFilesClient()
 
 # --- Configuration and Globals ---
-DEFAULT_KEY = os.getenv("MISTRAL_API_KEY", "")
+DEFAULT_MISTRAL_KEY = os.getenv("MISTRAL_API_KEY", "")
 PIXTRAL_MODEL = "pixtral-12b-2409"
 VIDEO_MODEL = "voxtral-mini-latest"
-STREAM_THRESHOLD = 20 * 1024 * 1024 # 20MB
+STREAM_THRESHOLD_BYTES = 20 * 1024 * 1024 # 20MB
 FFMPEG_BIN = shutil.which("ffmpeg")
-IMAGE_EXTS = (".jpg", ".jpeg", ".png", ".webp", ".gif")
-VIDEO_EXTS = (".mp4", ".mov", ".webm", ".mkv", ".avi", ".flv")
+IMAGE_EXTENSIONS = (".jpg", ".jpeg", ".png", ".webp", ".gif")
+VIDEO_EXTENSIONS = (".mp4", ".mov", ".webm", ".mkv", ".avi", ".flv")
 
 SYSTEM_INSTRUCTION = (
     "You are a clinical visual analyst. Only analyze media actually provided (image or video data). "
@@ -42,47 +86,55 @@ Image.MAX_IMAGE_PIXELS = 10000 * 10000
 DEFAULT_HEADERS = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"}
 
 # --- Temporary File Cleanup ---
-_temp_preview_files_to_delete = []
+_temp_files_to_delete = []
 
-def _cleanup_all_temp_preview_files():
-    """Removes all temporary files created for previews upon application exit."""
-    for f_path in list(_temp_preview_files_to_delete):
+def _cleanup_all_temp_files():
+    """Removes all temporary files created upon application exit."""
+    for f_path in list(_temp_files_to_delete):
         if os.path.exists(f_path):
             try:
                 os.remove(f_path)
             except Exception as e:
                 print(f"Error during final cleanup of {f_path}: {e}")
-    _temp_preview_files_to_delete.clear()
+    _temp_files_to_delete.clear()
 
-atexit.register(_cleanup_all_temp_preview_files)
+atexit.register(_cleanup_all_temp_files)
 
 # --- Mistral Client and API Helpers ---
-def get_client(key: Optional[str] = None):
+def get_client(api_key: Optional[str] = None):
     """
-    Returns a Mistral client instance. If the API key is missing,
-    a MistralAPIException is raised.
+    Returns a Mistral client instance. If the API key is missing or the client library
+    is not installed, a MistralAPIException is raised.
     """
-    api_key = (key or "").strip() or DEFAULT_KEY
+    if not _MISTRAL_CLIENT_INSTALLED:
+        raise MistralAPIException(
+            "Mistral AI client library is not installed. Please install it with 'pip install mistralai'.",
+            status_code=500 # Internal Server Error, as it's a server-side dependency issue
+        )
 
-    if not api_key:
+    key_to_use = (api_key or "").strip() or DEFAULT_MISTRAL_KEY
+    if not key_to_use:
         raise MistralAPIException(
             "Mistral API key is not set. Please provide it in the UI or as MISTRAL_API_KEY environment variable.",
             status_code=401 # Unauthorized
         )
 
-    # Directly instantiate the real Mistral client
-    client = Mistral(api_key=api_key)
-    return client
+    # If _MISTRAL_CLIENT_INSTALLED is True, this will be the real Mistral client.
+    # Otherwise, it's the placeholder that will raise on method call.
+    return Mistral(api_key=key_to_use)
 
 def is_remote(src: str) -> bool:
+    """Checks if a source string is a remote URL."""
     return bool(src) and src.startswith(("http://", "https://"))
 
 def ext_from_src(src: str) -> str:
+    """Extracts the file extension from a source string (path or URL)."""
     if not src: return ""
     _, ext = os.path.splitext((src or "").split("?")[0])
     return ext.lower()
 
 def safe_head(url: str, timeout: int = 6):
+    """Performs a HEAD request safely, returning None on error or status >= 400."""
     try:
         r = requests.head(url, timeout=timeout, allow_redirects=True, headers=DEFAULT_HEADERS)
         return None if r.status_code >= 400 else r
@@ -90,11 +142,13 @@ def safe_head(url: str, timeout: int = 6):
         return None
 
 def safe_get(url: str, timeout: int = 15):
+    """Performs a GET request safely, raising for status errors."""
     r = requests.get(url, timeout=timeout, headers=DEFAULT_HEADERS)
     r.raise_for_status()
     return r
 
 def _temp_file(data: bytes, suffix: str) -> str:
+    """Creates a temporary file with the given data and suffix, and registers it for cleanup."""
     if not data:
         return ""
 
@@ -102,10 +156,11 @@ def _temp_file(data: bytes, suffix: str) -> str:
     os.close(fd)
     with open(path, "wb") as f:
         f.write(data)
-    _temp_preview_files_to_delete.append(path)
+    _temp_files_to_delete.append(path)
     return path
 
-def fetch_bytes(src: str, stream_threshold: int = STREAM_THRESHOLD, timeout: int = 60, progress=None) -> bytes:
+def fetch_bytes(src: str, stream_threshold: int = STREAM_THRESHOLD_BYTES, timeout: int = 60, progress=None) -> bytes:
+    """Fetches content bytes from a local path or remote URL, with streaming for large files."""
     if progress is not None:
         progress(0.05, desc="Checking remote/local source...")
     if is_remote(src):
@@ -148,17 +203,18 @@ def fetch_bytes(src: str, stream_threshold: int = STREAM_THRESHOLD, timeout: int
         return data
 
 def convert_to_jpeg_bytes(img_bytes: bytes, base_h: int = 480) -> bytes:
+    """Converts image bytes to JPEG, resizing to a target height while maintaining aspect ratio."""
     try:
         img = Image.open(BytesIO(img_bytes))
     except UnidentifiedImageError:
-        print(f"Warning: convert_to_jpeg_bytes received unidentifiable image data.")
+        print("Warning: convert_to_jpeg_bytes received unidentifiable image data.")
         return b""
     except Exception as e:
         print(f"Warning: Error opening image for JPEG conversion: {e}")
         return b""
 
     try:
-        if getattr(img, "is_animated", False):
+        if getattr(img, "is_animated", False): # Handle animated images (e.g., GIFs) by taking the first frame
             img.seek(0)
     except Exception:
         pass
@@ -173,14 +229,16 @@ def convert_to_jpeg_bytes(img_bytes: bytes, base_h: int = 480) -> bytes:
     return buf.getvalue()
 
 def b64_bytes(b: bytes, mime: str = "image/jpeg") -> str:
+    """Encodes bytes to a Data URL string."""
     return f"data:{mime};base64," + base64.b64encode(b).decode("utf-8")
 
 def _ffprobe_streams(path: str) -> Optional[dict]:
+    """Uses ffprobe to get stream information for a media file."""
     if not FFMPEG_BIN:
         return None
     ffprobe_path = FFMPEG_BIN.replace("ffmpeg", "ffprobe") if "ffmpeg" in FFMPEG_BIN else "ffprobe"
     if not shutil.which(ffprobe_path):
-        ffprobe_path = "ffprobe"
+        ffprobe_path = "ffprobe" # Try raw 'ffprobe' if 'ffmpeg' replacement isn't found
         if not shutil.which(ffprobe_path):
             return None
 
@@ -194,6 +252,7 @@ def _ffprobe_streams(path: str) -> Optional[dict]:
         return None
 
 def _get_video_info_and_timestamps(media_path: str, sample_count: int) -> Tuple[Optional[dict], List[float]]:
+    """Extracts video info and generates timestamps for frame extraction."""
     info = _ffprobe_streams(media_path)
     duration = 0.0
     if info and "format" in info and "duration" in info["format"]:
@@ -209,12 +268,16 @@ def _get_video_info_and_timestamps(media_path: str, sample_count: int) -> Tuple[
             step = duration / (actual_sample_count + 1)
             timestamps = [step * (i + 1) for i in range(actual_sample_count)]
 
-    if not timestamps:
+    if not timestamps: # Fallback for very short videos or if duration couldn't be determined
         timestamps = [0.5, 1.0, 2.0, 3.0, 4.0][:sample_count]
 
     return info, timestamps
 
 def extract_frames_for_model_and_gallery(media_path: str, sample_count: int = 5, timeout_extract: int = 15, gallery_base_h: int = 1080, model_base_h: int = 1024, progress=None) -> Tuple[List[bytes], List[str]]:
+    """
+    Extracts frames from a video for model input and a gallery display.
+    Returns: (list of JPEG bytes for model, list of paths to JPEG files for gallery)
+    """
     frames_for_model: List[bytes] = []
     frame_paths_for_gallery: List[str] = []
 
@@ -277,6 +340,7 @@ def extract_frames_for_model_and_gallery(media_path: str, sample_count: int = 5,
     return frames_for_model, frame_paths_for_gallery
 
 def chat_complete(client, model: str, messages, timeout: int = 120, progress=None) -> str:
+    """Sends messages to the Mistral chat completion API with retry logic."""
     max_retries = 5
     initial_delay = 1.0
     for attempt in range(max_retries):
@@ -294,8 +358,9 @@ def chat_complete(client, model: str, messages, timeout: int = 120, progress=Non
                 return f"Empty response from model: {res}"
 
             first = choices[0]
-            msg = (first.message if hasattr(first, "message") else (first.get("message") if isinstance(first, dict) else first))
-            content = (msg.get("content") if isinstance(msg, dict) else getattr(msg, "content", None))
+            # Handle both object-style and dict-style responses
+            msg = getattr(first, "message", None) or (first.get("message") if isinstance(first, dict) else first)
+            content = getattr(msg, "content", None) or (msg.get("content") if isinstance(msg, dict) else None)
             return content.strip() if isinstance(content, str) else str(content)
 
         except MistralAPIException as e:
@@ -318,6 +383,7 @@ def chat_complete(client, model: str, messages, timeout: int = 120, progress=Non
     return "Error: Maximum retries reached for API call."
 
 def upload_file_to_mistral(client, path: str, filename: str | None = None, purpose: str = "batch", timeout: int = 120, progress=None) -> str:
+    """Uploads a file to the Mistral API, returning its file ID."""
     fname = filename or os.path.basename(path)
     max_retries = 3
     initial_delay = 1.0
@@ -355,13 +421,14 @@ def upload_file_to_mistral(client, path: str, filename: str | None = None, purpo
     raise RuntimeError("File upload failed: Maximum retries reached.")
 
 def determine_media_type(src: str, progress=None) -> Tuple[bool, bool]:
+    """Provides an initial hint about media type based on extension or content-type header."""
     is_image = False
     is_video = False
     ext = ext_from_src(src)
 
-    if ext in IMAGE_EXTS:
+    if ext in IMAGE_EXTENSIONS:
         is_image = True
-    elif ext in VIDEO_EXTS:
+    elif ext in VIDEO_EXTENSIONS:
         is_video = True
 
     if is_remote(src):
@@ -378,6 +445,7 @@ def determine_media_type(src: str, progress=None) -> Tuple[bool, bool]:
     return is_image, is_video
 
 def analyze_image_structured(client, img_bytes: bytes, prompt: str, progress=None) -> str:
+    """Analyzes an image using the PixTRAL model."""
     try:
         if progress is not None:
             progress(0.3, desc="Preparing image for analysis...")
@@ -399,11 +467,16 @@ def analyze_image_structured(client, img_bytes: bytes, prompt: str, progress=Non
         return f"Error analyzing image: {e}"
 
 def analyze_video_cohesive(client, video_path: str, prompt: str, progress=None) -> Tuple[str, List[str]]:
+    """
+    Analyzes a video using the VoxTRAL model (if available) or by extracting frames
+    and using PixTRAL as a fallback.
+    Returns: (analysis result text, list of paths to gallery frames)
+    """
     gallery_frame_paths: List[str] = []
     try:
         if progress is not None:
             progress(0.3, desc="Uploading video for full analysis...")
-        file_id = upload_file_to_mistral(client, video_path, filename=os.path.basename(video_path), progress=progress)
+        file_id = upload_file_to_mistral(client, video_path, filename=os.path.basename(video_path), purpose="batch", progress=progress)
 
         messages = [
             {"role": "system", "content": SYSTEM_INSTRUCTION},
@@ -413,20 +486,22 @@ def analyze_video_cohesive(client, video_path: str, prompt: str, progress=None)
         ]
         result = chat_complete(client, VIDEO_MODEL, messages, progress=progress)
 
+        # Still extract frames for gallery even if full video upload was successful
         _, gallery_frame_paths = extract_frames_for_model_and_gallery(
             video_path, sample_count=6, gallery_base_h=1080, model_base_h=1024, progress=progress
         )
         return result, gallery_frame_paths
     except Exception as e:
+        print(f"Warning: Video upload/full analysis failed ({e}). Extracting frames as fallback...")
         if progress is not None:
-            progress(0.35, desc=f"Upload failed for video ({e}). Extracting frames as fallback...")
+            progress(0.35, desc=f"Video upload failed ({type(e).__name__}). Extracting frames as fallback...")
 
         frames_for_model_bytes, gallery_frame_paths = extract_frames_for_model_and_gallery(
             video_path, sample_count=6, gallery_base_h=1080, model_base_h=1024, progress=progress
         )
 
         if not frames_for_model_bytes:
-            return f"Error: could not upload video and no frames could be extracted. ({e})", []
+            return f"Error: could not upload video and no frames could be extracted for fallback. ({e})", []
 
         image_entries = []
         for i, fb in enumerate(frames_for_model_bytes, start=1):
@@ -439,6 +514,7 @@ def analyze_video_cohesive(client, video_path: str, prompt: str, progress=None)
                     "meta": {"frame_index": i},
                 }
             )
+        # Consolidate frames for a cohesive narrative, as per requirement
         content = [{"type": "text", "text": prompt + "\n\nPlease consolidate observations across these frames into a single cohesive narrative."}] + image_entries
         messages = [
             {"role": "system", "content": SYSTEM_INSTRUCTION},
@@ -449,15 +525,20 @@ def analyze_video_cohesive(client, video_path: str, prompt: str, progress=None)
 
 # --- FFmpeg Helpers for Preview ---
 def _convert_video_for_preview_if_needed(path: str) -> str:
+    """
+    Converts a video to a web-friendly MP4 format if necessary for preview.
+    Returns the path to the converted video or the original path if no conversion needed/failed.
+    """
     if not FFMPEG_BIN or not os.path.exists(path):
         return path
 
+    # Check if it's already a web-friendly MP4 (H.264/AVC1, H.265)
     if path.lower().endswith((".mp4", ".m4v")):
         info = _ffprobe_streams(path)
         if info:
             video_streams = [s for s in info.get("streams", []) if s.get("codec_type") == "video"]
             if video_streams and any(s.get("codec_name") in ("h264", "h265", "avc1") for s in video_streams):
-                return path
+                return path # Already compatible, no conversion needed
 
     out_path = _temp_file(b"", suffix=".mp4")
     if not out_path:
@@ -466,24 +547,29 @@ def _convert_video_for_preview_if_needed(path: str) -> str:
 
     cmd = [
         FFMPEG_BIN, "-y", "-i", path,
-        "-c:v", "libx264", "-preset", "veryfast", "-crf", "28",
-        "-c:a", "aac", "-b:a", "128k",
-        "-movflags", "+faststart", out_path,
-        "-map_metadata", "-1"
+        "-c:v", "libx264", "-preset", "veryfast", "-crf", "28", # H.264 codec
+        "-c:a", "aac", "-b:a", "128k", # AAC audio
+        "-movflags", "+faststart", out_path, # Optimize for web streaming
+        "-map_metadata", "-1" # Remove metadata
     ]
     try:
         subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=60)
         return out_path
     except Exception as e:
         print(f"Error converting video for preview: {e}")
-        if out_path in _temp_preview_files_to_delete:
-            _temp_preview_files_to_delete.remove(out_path)
+        # If conversion fails, remove the failed temp file and return original path
+        if out_path in _temp_files_to_delete:
+            _temp_files_to_delete.remove(out_path)
         try: os.remove(out_path)
         except Exception: pass
         return path
 
 # --- Preview Generation Logic ---
 def _get_playable_preview_path_from_raw(src_url: str, raw_bytes: bytes, is_image_hint: bool, is_video_hint: bool) -> str:
+    """
+    Generates a playable preview file (JPEG for image, MP4 for video) from raw bytes.
+    Returns the path to the generated preview file.
+    """
     if not raw_bytes:
         print(f"Error: No raw bytes provided for preview generation of {src_url}.")
         return ""
@@ -493,14 +579,14 @@ def _get_playable_preview_path_from_raw(src_url: str, raw_bytes: bytes, is_image
         Image.open(BytesIO(raw_bytes)).verify()
         is_actually_image = True
     except (UnidentifiedImageError, Exception):
-        pass
+        pass # Not a verifiable image, proceed to video or fallback logic
 
     if is_actually_image:
         jpeg_bytes = convert_to_jpeg_bytes(raw_bytes, base_h=1024)
         if jpeg_bytes:
             return _temp_file(jpeg_bytes, suffix=".jpg")
-        return "" # Failed image conversion, do not fall through to video logic
-    elif is_video_hint:
+        return "" # Failed image conversion
+    elif is_video_hint: # If it's not an image, and was hinted as video
         temp_raw_video_path = _temp_file(raw_bytes, suffix=ext_from_src(src_url) or ".mp4")
         if not temp_raw_video_path:
             print(f"Error: Failed to create temporary raw video file for {src_url}.")
@@ -508,7 +594,7 @@ def _get_playable_preview_path_from_raw(src_url: str, raw_bytes: bytes, is_image
 
         playable_path = _convert_video_for_preview_if_needed(temp_raw_video_path)
         return playable_path
-    elif is_image_hint: # Fallback to image hint if no definite image and not a video hint
+    elif is_image_hint: # Fallback: if hinted image but not verifiable, still try conversion
          jpeg_bytes = convert_to_jpeg_bytes(raw_bytes, base_h=1024)
          if jpeg_bytes:
              return _temp_file(jpeg_bytes, suffix=".jpg")
@@ -519,30 +605,32 @@ def _get_playable_preview_path_from_raw(src_url: str, raw_bytes: bytes, is_image
 
 
 # --- Gradio Interface Logic ---
-css = ".preview_media img, .preview_media video { max-width: 100%; height: auto; border-radius:6px; }"
+GRADIO_CSS = ".preview_media img, .preview_media video { max-width: 100%; height: auto; border-radius:6px; }"
 
-def _btn_label_for_status(status: str) -> str:
+def _get_button_label_for_status(status: str) -> str:
+    """Returns the appropriate button label based on the processing status."""
     return {"idle": "Submit", "busy": "Processing…", "done": "Done!", "error": "Retry"}.get(status, "Submit")
 
 def create_demo():
-    with gr.Blocks(title="Flux Multimodal", css=css) as demo:
+    """Creates the Gradio interface for Flux Multimodal analysis."""
+    with gr.Blocks(title="Flux Multimodal", css=GRADIO_CSS) as demo:
         with gr.Row():
             with gr.Column(scale=1):
                 preview_image = gr.Image(label="Preview Image", type="filepath", elem_classes="preview_media", visible=False)
                 preview_video = gr.Video(label="Preview Video", elem_classes="preview_media", visible=False, format="mp4")
                 screenshot_gallery = gr.Gallery(label="Extracted Screenshots", columns=5, rows=1, height="auto", object_fit="contain", visible=False)
-                preview_status = gr.Textbox(label="Preview status", interactive=False, lines=1, value="", visible=True)
+                preview_status_text = gr.Textbox(label="Preview status", interactive=False, lines=1, value="", visible=True)
             with gr.Column(scale=2):
                 url_input = gr.Textbox(label="Image / Video URL", placeholder="https://...", lines=1)
                 with gr.Accordion("Prompt (optional)", open=False):
                     custom_prompt = gr.Textbox(label="Prompt", lines=4, value="")
                 with gr.Accordion("Mistral API Key (optional)", open=False):
-                    api_key = gr.Textbox(label="Mistral API Key", type="password", max_lines=1)
+                    api_key_input = gr.Textbox(label="Mistral API Key", type="password", max_lines=1)
                 with gr.Row():
                     submit_btn = gr.Button("Submit")
                     clear_btn = gr.Button("Clear")
-                progress_md = gr.Markdown("Idle")
-                output_md = gr.Markdown("")
+                progress_markdown = gr.Markdown("Idle")
+                output_markdown = gr.Markdown("")
 
                 status_state = gr.State("idle")
                 main_preview_path_state = gr.State("") # Path to the playable preview file (image or video)
@@ -552,15 +640,14 @@ def create_demo():
         def clear_all_ui_and_files_handler():
             """
             Cleans up all tracked temporary files and resets all relevant UI components and states.
-            This function is meant to be called when the user explicitly clicks "Clear".
             """
-            for f_path in list(_temp_preview_files_to_delete):
+            for f_path in list(_temp_files_to_delete):
                 if os.path.exists(f_path):
                     try:
                         os.remove(f_path)
                     except Exception as e:
                         print(f"Error during proactive cleanup of {f_path}: {e}")
-            _temp_preview_files_to_delete.clear()
+            _temp_files_to_delete.clear()
 
             return "", \
                    gr.update(value=None, visible=False), \
@@ -583,13 +670,14 @@ def create_demo():
                 preview_video,
                 screenshot_gallery,
                 status_state,
-                progress_md,
-                output_md,
+                progress_markdown,
+                output_markdown,
                 main_preview_path_state,
                 screenshot_paths_state,
-                preview_status,
+                preview_status_text,
                 raw_media_path_state
-            ]
+            ],
+            queue=False
         )
 
         def load_main_preview_and_setup_for_analysis(
@@ -599,6 +687,10 @@ def create_demo():
             current_screenshot_paths: List[str],
             progress=gr.Progress()
         ):
+            """
+            Loads media from URL, generates a preview, and sets up temporary files for analysis.
+            Also handles cleanup of previously loaded media.
+            """
             # --- Proactive cleanup of old files related to previous load ---
             files_to_clean_up_now = []
             if current_main_preview_path and os.path.exists(current_main_preview_path):
@@ -610,8 +702,8 @@ def create_demo():
                     files_to_clean_up_now.append(path)
 
             for f_path in files_to_clean_up_now:
-                if f_path in _temp_preview_files_to_delete:
-                    _temp_preview_files_to_delete.remove(f_path)
+                if f_path in _temp_files_to_delete:
+                    _temp_files_to_delete.remove(f_path)
                 try: os.remove(f_path)
                 except Exception as e: print(f"Error cleaning up old temp file {f_path}: {e}")
 
@@ -628,7 +720,7 @@ def create_demo():
                 return img_update_clear, video_update_clear, gallery_update_clear, \
                        preview_status_clear, main_path_clear, raw_media_path_clear, screenshot_paths_clear
 
-            temp_raw_path_for_analysis = "" # Initialize to ensure it's in scope for finally block
+            temp_raw_path_for_analysis = ""
             try:
                 progress(0.01, desc="Downloading media for preview and analysis...")
                 raw_bytes_for_analysis = fetch_bytes(url, timeout=60, progress=progress)
@@ -650,8 +742,8 @@ def create_demo():
 
                 if not local_playable_path:
                     # If preview failed, cleanup the temp_raw_path_for_analysis as well
-                    if temp_raw_path_for_analysis in _temp_preview_files_to_delete:
-                        _temp_preview_files_to_delete.remove(temp_raw_path_for_analysis)
+                    if temp_raw_path_for_analysis in _temp_files_to_delete:
+                        _temp_files_to_delete.remove(temp_raw_path_for_analysis)
                     try: os.remove(temp_raw_path_for_analysis)
                     except Exception as e: print(f"Error during cleanup of raw temp file {temp_raw_path_for_analysis}: {e}")
 
@@ -660,8 +752,8 @@ def create_demo():
                            main_path_clear, raw_media_path_clear, screenshot_paths_clear
 
                 ext = ext_from_src(local_playable_path)
-                is_img_preview = ext in IMAGE_EXTS
-                is_vid_preview = ext in VIDEO_EXTS
+                is_img_preview = ext in IMAGE_EXTENSIONS
+                is_vid_preview = ext in VIDEO_EXTENSIONS
 
                 if is_img_preview:
                     return gr.update(value=local_playable_path, visible=True), gr.update(value=None, visible=False), \
@@ -673,13 +765,13 @@ def create_demo():
                            local_playable_path, temp_raw_path_for_analysis, screenshot_paths_clear
                 else:
                     # If local_playable_path exists but is not image/video, clean it up
-                    if local_playable_path in _temp_preview_files_to_delete:
-                        _temp_preview_files_to_delete.remove(local_playable_path)
+                    if local_playable_path in _temp_files_to_delete:
+                        _temp_files_to_delete.remove(local_playable_path)
                     try: os.remove(local_playable_path)
                     except Exception as e: print(f"Error during cleanup of unplayable temp file {local_playable_path}: {e}")
                     # Also clean up raw_media_path if the playable path was not generated successfully
-                    if temp_raw_path_for_analysis in _temp_preview_files_to_delete:
-                        _temp_preview_files_to_delete.remove(temp_raw_path_for_analysis)
+                    if temp_raw_path_for_analysis in _temp_files_to_delete:
+                        _temp_files_to_delete.remove(temp_raw_path_for_analysis)
                     try: os.remove(temp_raw_path_for_analysis)
                     except Exception as e: print(f"Error during cleanup of raw temp file {temp_raw_path_for_analysis}: {e}")
 
@@ -690,22 +782,25 @@ def create_demo():
             except Exception as e:
                 # If an error occurred during loading, clear all relevant paths.
                 if os.path.exists(temp_raw_path_for_analysis):
-                    if temp_raw_path_for_analysis in _temp_preview_files_to_delete:
-                        _temp_preview_files_to_delete.remove(temp_raw_path_for_analysis)
+                    if temp_raw_path_for_analysis in _temp_files_to_delete:
+                        _temp_files_to_delete.remove(temp_raw_path_for_analysis)
                     try: os.remove(temp_raw_path_for_analysis)
                     except Exception as ex: print(f"Error during cleanup of raw temp file {temp_raw_path_for_analysis} on error: {ex}")
 
                 return img_update_clear, video_update_clear, gallery_update_clear, \
-                       gr.update(value=f"Preview load failed: {e}", visible=True), \
+                       gr.update(value=f"Preview load failed: {type(e).__name__}: {e}", visible=True), \
                        main_path_clear, raw_media_path_clear, screenshot_paths_clear
 
         url_input.change(
             fn=load_main_preview_and_setup_for_analysis,
             inputs=[url_input, main_preview_path_state, raw_media_path_state, screenshot_paths_state],
-            outputs=[preview_image, preview_video, screenshot_gallery, preview_status, main_preview_path_state, raw_media_path_state, screenshot_paths_state]
+            outputs=[preview_image, preview_video, screenshot_gallery, preview_status_text, main_preview_path_state, raw_media_path_state, screenshot_paths_state]
         )
 
         def worker(url: str, prompt: str, key: str, current_main_preview_path: str, raw_media_path: str, progress=gr.Progress()):
+            """
+            The main worker function that performs media analysis using Mistral models.
+            """
             generated_screenshot_paths: List[str] = []
             result_text = ""
 
@@ -724,16 +819,21 @@ def create_demo():
                 is_actually_image_for_analysis = False
                 is_actually_video_for_analysis = False
 
+                # Determine media type for analysis robustly
                 try:
                     Image.open(BytesIO(raw_bytes_for_analysis)).verify()
                     is_actually_image_for_analysis = True
                 except UnidentifiedImageError:
-                    is_actually_video_for_analysis = True
+                    # If PIL can't identify it as an image, check if it has a video extension.
+                    if ext_from_src(raw_media_path) in VIDEO_EXTENSIONS:
+                        is_actually_video_for_analysis = True
                 except Exception as e:
-                    print(f"Warning: PIL error during image verification for raw analysis media ({raw_media_path}): {e}. Assuming video type for fallback.")
-                    is_actually_video_for_analysis = True
+                    # Catch other PIL errors (e.g., truncated, memory, etc.).
+                    print(f"Warning: PIL error during image verification for raw analysis media ({raw_media_path}): {e}. Checking for video extension.")
+                    if ext_from_src(raw_media_path) in VIDEO_EXTENSIONS:
+                        is_actually_video_for_analysis = True
 
-                client = get_client(key)
+                client = get_client(key) # This will raise MistralAPIException if library not installed or key missing
 
                 if is_actually_video_for_analysis:
                     progress(0.25, desc="Running full-video analysis")
@@ -742,37 +842,42 @@ def create_demo():
                     progress(0.20, desc="Running image analysis")
                     result_text = analyze_image_structured(client, raw_bytes_for_analysis, prompt, progress=progress)
                 else:
-                    return "error", "Error: Could not definitively determine media type for analysis after byte inspection.", current_main_preview_path, []
+                    return "error", "Error: Could not definitively determine media type for analysis after byte inspection and extension check. Please check the URL.", current_main_preview_path, []
 
                 status = "done" if not (isinstance(result_text, str) and result_text.lower().startswith("error")) else "error"
                 return status, result_text, current_main_preview_path, generated_screenshot_paths
 
+            except MistralAPIException as e:
+                # Catch API key missing or client not installed errors from get_client or client method calls
+                return "error", f"**Mistral API Error:** {e.message}", current_main_preview_path, []
             except Exception as exc:
-                return "error", f"Unexpected worker error: {exc}", current_main_preview_path, []
+                return "error", f"**Unexpected worker error:** {type(exc).__name__}: {exc}", current_main_preview_path, []
 
         submit_btn.click(
             fn=worker,
-            inputs=[url_input, custom_prompt, api_key, main_preview_path_state, raw_media_path_state],
-            outputs=[status_state, output_md, main_preview_path_state, screenshot_paths_state],
+            inputs=[url_input, custom_prompt, api_key_input, main_preview_path_state, raw_media_path_state],
+            outputs=[status_state, output_markdown, main_preview_path_state, screenshot_paths_state],
             show_progress="full",
-            show_progress_on=progress_md,
+            show_progress_on=progress_markdown,
         )
 
-        status_state.change(fn=_btn_label_for_status, inputs=[status_state], outputs=[submit_btn])
+        status_state.change(fn=_get_button_label_for_status, inputs=[status_state], outputs=[submit_btn], queue=False)
 
-        def status_to_progress_text(s):
+        def _status_to_progress_text(s):
+            """Converts internal status to user-friendly progress text."""
             return {"idle": "Idle", "busy": "Processing…", "done": "Completed", "error": "Error — see output"}.get(s, s)
-        status_state.change(fn=status_to_progress_text, inputs=[status_state], outputs=[progress_md])
+        status_state.change(fn=_status_to_progress_text, inputs=[status_state], outputs=[progress_markdown], queue=False)
 
         def _update_preview_components(current_main_preview_path: str, current_screenshot_paths: List[str]):
+            """Updates the visibility and content of preview components (image, video, gallery)."""
             img_update = gr.update(value=None, visible=False)
             video_update = gr.update(value=None, visible=False)
 
             if current_main_preview_path:
                 ext = ext_from_src(current_main_preview_path)
-                if ext in IMAGE_EXTS:
+                if ext in IMAGE_EXTENSIONS:
                     img_update = gr.update(value=current_main_preview_path, visible=True)
-                elif ext in VIDEO_EXTS:
+                elif ext in VIDEO_EXTENSIONS:
                     video_update = gr.update(value=current_main_preview_path, visible=True)
                 else:
                     print(f"Warning: Unknown media type for main preview path: {current_main_preview_path}")
@@ -780,6 +885,7 @@ def create_demo():
             gallery_update = gr.update(value=current_screenshot_paths, visible=bool(current_screenshot_paths))
             return img_update, video_update, gallery_update
 
+        # These change events use queue=False to ensure UI updates are immediate and don't block
         main_preview_path_state.change(
             fn=_update_preview_components,
             inputs=[main_preview_path_state, screenshot_paths_state],