add comments

demo/app.py

@@ -20,7 +20,12 @@ def render_health_panel(gemini_api_key: str | None = None) -> str:
 
 
 def create_app() -> gr.Blocks:
-    """Create the Gradio application with a minimal notebook-like health cell."""
+    """Create the Gradio Blocks application used in the Hugging Face Space.
+
+    The layout is intentionally notebook-like: each conceptual unit
+    (problem, health, demos, wrap-up) is encapsulated in its own module
+    and rendered as a "cell" to keep the main app glue straightforward.
+    """
     with gr.Blocks(title="Aileen3 Demo") as demo:
         gr.HTML(f"<style>{CELL_CSS}</style>")
 

demo/context_biased_transcription_cell.py

@@ -20,6 +20,8 @@ from problem_cell import (
 
 log = logging.getLogger(__name__)
 
+# Context-biased transcription can take a bit longer; use more generous
+# polling defaults here than in the other cells.
 MAX_POLL_ATTEMPTS = 20
 POLL_WAIT_SECONDS = 58
 
@@ -91,7 +93,13 @@ async def _poll_until_done(
 
 
 async def _run_transcription_flow(gemini_api_key: str) -> Tuple[str, str]:
-    """Drive the MCP media tools to run a context-biased transcription demo."""
+    """Drive the MCP media tools to run a context-biased transcription demo.
+
+    This mirrors a typical client-side flow:
+    - retrieve media via `start_media_retrieval`,
+    - derive a textual prior from the YouTube description, and
+    - call `start_media_transcription` with that prior as context.
+    """
     try:
         from fastmcp import Client  # type: ignore[import-untyped]
         from fastmcp.client.transports import StdioTransport  # type: ignore[import-untyped]
@@ -99,6 +107,9 @@ async def _run_transcription_flow(gemini_api_key: str) -> Tuple[str, str]:
         status = render_status_box(f"fastmcp is not available in this environment: {exc}", "fail")
         return status, ""
 
+    # As in the other cells we spawn the MCP server as a subprocess and
+    # point PYTHONPATH at `mcp/src` so that editable installs are not
+    # required to run the demo locally.
     repo_root = Path(__file__).resolve().parents[1]
     mcp_src = repo_root / "mcp" / "src"
     existing_py_path = os.environ.get("PYTHONPATH", "")

demo/demo_logging.py

@@ -5,6 +5,9 @@ import os
 from pathlib import Path
 from typing import Optional
 
+# Lightweight logging helper for the Gradio demo.
+# The MCP server has its own logging configuration; this module keeps
+# demo-specific logs in a separate file referenced from the UI.
 LOGGER_NAME = "aileen3_demo"
 LOG_LEVEL_ENV = "AILEEN3_DEMO_LOGLEVEL"
 

demo/health.py

@@ -15,6 +15,7 @@ from itertools import zip_longest
 from typing import Iterable
 
 
+# Version and environment constraints for a "green" health check in the demo.
 MIN_DENO_VERSION = (2, 0, 0)
 MIN_YTDLP_VERSION = (2025, 11, 12)
 MIN_FFMPEG_VERSION = (4, 0)
@@ -141,6 +142,9 @@ def _check_mcp_health(gemini_api_key: str | None = None) -> ToolStatus:
     except Exception as exc:  # pragma: no cover - defensive
         return ToolStatus(label, False, f"fastmcp missing: {exc}")
 
+    # When running inside the Hugging Face Space, the repo root is the
+    # working directory; keep this logic in sync with the Dockerfile so
+    # that imports work both locally and in production.
     repo_root = Path(__file__).resolve().parents[1]
     mcp_src = repo_root / "mcp" / "src"
     existing_py_path = os.environ.get("PYTHONPATH", "")

demo/layout.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from contextlib import contextmanager
 import gradio as gr
 
+# Shared CSS used by all "cells" in the notebook-style demo.
 CELL_CSS = """
 .cell-wrapper {
     border: 1px solid rgba(0, 0, 0, 0.9);
@@ -68,6 +69,12 @@ CELL_CSS = """
 
 @contextmanager
 def cell(title: str):
+    """Context manager that renders a titled notebook-style cell.
+
+    Usage:
+        with cell("My title"):
+            ...  # add components that appear inside the cell
+    """
     with gr.Column(elem_classes="cell-wrapper") as column:
         gr.HTML(f"<div class='cell-title'>{title}</div>")
         yield column

demo/media_analysis_cell.py

@@ -21,9 +21,11 @@ from slide_utils import normalize_slide_entries
 log = get_demo_logger(__name__)
 DEMO_LOG_PATH = str(get_demo_log_path())
 
+# Polling strategy for long-running MCP jobs started from the demo.
 MAX_POLL_ATTEMPTS = 3
 POLL_WAIT_SECONDS = 54
 
+# Fixed video used in the expectation-driven analysis cell.
 ANALYSIS_VIDEO_URL = "https://youtu.be/eXP-PvKcI9A"
 
 
@@ -133,7 +135,13 @@ async def _run_media_analysis_flow(
     prior_knowledge: str,
     questions: str,
 ) -> Tuple[str, str, List[list]]:
-    """Drive the MCP tools to run expectation-driven media analysis for a fixed video."""
+    """Drive the MCP tools to run expectation-driven media analysis for a fixed video.
+
+    The flow mirrors how an MCP-capable client would typically use the tools:
+    - start_media_retrieval → wait for cached or finished download
+    - start_media_analysis → wait for the expectation-driven briefing
+    - get_extracted_slides → fetch slide stills used as priors
+    """
     try:
         from fastmcp import Client  # type: ignore[import-untyped]
         from fastmcp.client.transports import StdioTransport  # type: ignore[import-untyped]
@@ -157,6 +165,9 @@ async def _run_media_analysis_flow(
         questions_len,
     )
 
+    # Spawn the MCP server as a subprocess, pointing PYTHONPATH at the
+    # local `mcp/src` tree so this file keeps working both locally and
+    # inside the Space image.
     repo_root = Path(__file__).resolve().parents[1]
     mcp_src = repo_root / "mcp" / "src"
     existing_py_path = os.environ.get("PYTHONPATH", "")

demo/problem_cell.py

@@ -54,6 +54,12 @@ def _extract_video_id(video_url: str) -> str | None:
 
 
 def _fetch_transcript(video_url: str) -> tuple[str | None, str | None]:
+    """Retrieve or cache a plain-text transcript for the given YouTube URL.
+
+    For the purposes of this cell we rely on YouTube auto captions via
+    yt-dlp; the heavy-duty Gemini-based transcription lives in the MCP
+    tools and separate demo cells.
+    """
     TRANSCRIPTION_CACHE.mkdir(parents=True, exist_ok=True)
 
     if YoutubeDL is None:  # pragma: no cover - dependency should always be present
@@ -62,8 +68,10 @@ def _fetch_transcript(video_url: str) -> tuple[str | None, str | None]:
     if not video_id:
         return None, "That does not look like a valid YouTube URL with a video id."
 
-    # Align cache layout with `media_tools`: transcription cache under BASE_CACHE/transcription
-    # using a stable reference derived from the YouTube video id when available.
+    # Align cache layout with `media_tools`: transcription cache under
+    # BASE_CACHE/transcription using a stable reference derived from the
+    # YouTube video id when available. This keeps the demo and MCP server
+    # caches compatible and easier to inspect.
     reference = f"youtube_{hashlib.sha256(video_id.encode('utf-8')).hexdigest()[:32]}"
     cache_path = _transcription_cache_path(reference)
     if cache_path.exists():

demo/slide_utils.py

@@ -5,7 +5,13 @@ from typing import Any, Iterable
 
 
 def _data_uri_from(value: Any) -> str | None:
-    """Convert raw slide/image representations into a data URI string."""
+    """Convert raw slide/image representations into a data URI string.
+
+    This accepts several shapes that can appear in MCP tool responses:
+    - plain bytes
+    - dicts or objects with ``data``/``mimeType`` fields
+    - already-encoded ``data:...`` URIs
+    """
 
     if not value:
         return None

demo/translation_cell.py

@@ -36,7 +36,12 @@ async def _run_translation_flow(
     language: str,
     slide_index_text: str,
 ) -> Tuple[str, str, Optional[Image.Image]]:
-    """Drive the MCP tools to translate a representative slide from the fixed video."""
+    """Drive the MCP tools to translate a particular slide from the fixed video.
+
+    The flow reuses the same retrieval and slide-extraction pipeline as the
+    expectation-driven analysis cell, then calls the dedicated `translate_slide`
+    MCP tool to produce a target-language slide image.
+    """
     try:
         from fastmcp import Client  # type: ignore[import-untyped]
         from fastmcp.client.transports import StdioTransport  # type: ignore[import-untyped]
@@ -76,6 +81,8 @@ async def _run_translation_flow(
         slide_index_text,
     )
 
+    # Spawn the MCP server as a subprocess with PYTHONPATH pointing at
+    # the local `mcp/src` tree so this stays self-contained in the Space.
     repo_root = Path(__file__).resolve().parents[1]
     mcp_src = repo_root / "mcp" / "src"
     existing_py_path = os.environ.get("PYTHONPATH", "")

mcp/src/aileen3_mcp/logging_utils.py

@@ -4,7 +4,8 @@ import logging
 import os
 from pathlib import Path
 
-# Logging paths
+# Logging paths used by the MCP package.
+# The demo UI links directly to these files, so keep the layout stable.
 BASE_CACHE = Path(os.environ.get("AILEEN3_CACHE_DIR", Path.home() / ".cache" / "aileen3"))
 LOG_DIR = BASE_CACHE / "logs"
 LOG_FILE = LOG_DIR / "aileen3-mcp.log"
@@ -12,6 +13,7 @@ PACKAGE_LOGGER_NAME = "aileen3_mcp"
 
 
 def _resolve_level() -> int:
+    """Resolve the log level from ``AILEEN3_LOGLEVEL`` or fall back to INFO."""
     level_name = os.environ.get("AILEEN3_LOGLEVEL", "").upper() or "INFO"
     level = getattr(logging, level_name, None)
     if isinstance(level, int):

mcp/src/aileen3_mcp/media_tools.py

@@ -36,6 +36,9 @@ TRANSCRIPTION_CACHE = BASE_CACHE / "transcription"
 for _path in (MEDIA_CACHE, SLIDE_CACHE, ANALYSIS_CACHE, TRANSCRIPTION_CACHE):
     _path.mkdir(parents=True, exist_ok=True)
 
+# Optional debug artefacts for inspecting Gemini responses and intermediate files.
+# These are deliberately kept out of the main cache to avoid interfering with
+# normal operation and are only written when AILEEN3_DEBUG is enabled.
 DEBUG = os.environ.get("AILEEN3_DEBUG", "").lower() in {"1", "true", "yes", "on"}
 DEBUG_DIR = Path(tempfile.gettempdir()) / "aileen3-debug"
 if DEBUG:
@@ -71,6 +74,12 @@ class _YDLLogger:
 
 @contextmanager
 def _silence_stdio():
+    """Context manager that temporarily captures stdout/stderr of noisy libraries.
+
+    yt-dlp and ffmpeg are quite chatty; redirecting their output keeps the
+    Space logs readable while still allowing us to inspect any errors via
+    Python logging where needed.
+    """
     buf_out = io.StringIO()
     buf_err = io.StringIO()
     with redirect_stdout(buf_out), redirect_stderr(buf_err):

mcp/src/aileen3_mcp/server.py

@@ -23,14 +23,27 @@ class HealthResult:
 
 
 def make_app() -> FastMCP:
-    """Create the MCP application with available tools."""
+    """Create the MCP application with all tools registered on a FastMCP instance.
+
+    This function is the single entry point for tool registration:
+    - it wires up lightweight health checks used by the demo Space, and
+    - it delegates to :func:`register_media_tools` for all long-running media flows.
+    """
     app = FastMCP("aileen3-mcp")
 
     @app.tool()
     def health() -> dict:
-        """Return a basic health payload including ffmpeg and Gemini env availability."""
+        """Return a basic health payload including ffmpeg and Gemini env availability.
+
+        This mirrors the Gradio health cell and is intentionally cheap:
+        it only checks for the *presence* of ffmpeg and a Gemini API key,
+        leaving deeper checks to the demo-side health probe.
+        """
 
         def _ffmpeg_ok() -> tuple[bool, str]:
+            # Keep this probe very small: just check that the binary is
+            # callable and returns a version string, without running any
+            # actual media processing pipeline.
             binary = shutil.which("ffmpeg")
             if not binary:
                 return False, "ffmpeg not found on PATH"
@@ -131,18 +144,20 @@ def make_app() -> FastMCP:
         return {"videos": videos}
 
     # Register media analysis tools:
-    #   - start_media_retrieval
-    #   - get_media_retrieval_status
-    #   - start_slide_extraction
-    #   - get_extracted_slides
-    #   - start_media_analysis
-    #   - get_media_analysis_result
+    #   - start_media_retrieval / get_media_retrieval_status
+    #   - start_slide_extraction / get_extracted_slides
+    #   - start_media_analysis / get_media_analysis_result
+    #   - start_media_transcription / get_media_transcription_result
+    #
+    # Each of these is exposed as an MCP tool that can be called from
+    # Claude Desktop, the Aileen 3 Agent, or the Gradio demo.
     register_media_tools(app)
 
     return app
 
 
 def main() -> None:
+    """Configure logging and run the MCP server over stdio."""
     configure_logging()
     app = make_app()
     app.run()  # stdio transport by default