model loading + fix preview + tracing + pptx skills

.gitignore

@@ -9,3 +9,5 @@ models/
 *.egg-info/
 dist/
 build/
+
+outputs/traces

apps/gradio-space/src/gradio_space/app.py

@@ -2,7 +2,9 @@ import os
 
 import gradio as gr
 
+from gradio_space.model_loading import preload_active_model
 from gradio_space.tabs import build_chat_tab, build_education_pptx_tab
+from gradio_space.tabs.education_pptx import gradio_allowed_paths
 from inference.config import get_app_config
 
 _app_config = get_app_config()
@@ -40,13 +42,13 @@ Part of the [Build Small Hackathon](https://huggingface.co/build-small-hackathon
     return demo
 
 
-demo = build_demo()
-
-
 def main() -> None:
+    preload_active_model()
+    demo = build_demo()
     demo.launch(
         server_name="0.0.0.0",
         server_port=int(os.environ.get("PORT", "7860")),
+        allowed_paths=gradio_allowed_paths(),
     )
 
 

apps/gradio-space/src/gradio_space/model_loading.py

@@ -69,10 +69,23 @@ def warmup(model_key: str | None = None) -> str:
     device_hint = runtime_device_hint(key)
     return (
         f"Preset `{key}` selected ({model.backend}, {device_hint}). "
-        "Weights load on the first request."
+        "Loading weights…"
     )
 
 
+def preload_active_model() -> str:
+    """Load the active preset at startup so the first request is fast."""
+    key = get_active_model_key()
+    print(f"[startup] Loading model preset `{key}`…", flush=True)
+    error = ensure_model_loaded(key)
+    if error:
+        print(f"[startup] {error}", flush=True)
+        return error
+    status = warmup(key)
+    print(f"[startup] {status}", flush=True)
+    return status
+
+
 def model_status(model_key: str) -> str:
     model = get_model_config(model_key)
     return f"**{model.label}**\n\n- Backend: `{model.backend}`\n- {warmup(model_key)}"

apps/gradio-space/src/gradio_space/tabs/chat.py

@@ -1,6 +1,6 @@
 import gradio as gr
 
-from gradio_space.model_loading import chat, model_status, warmup
+from gradio_space.model_loading import chat, model_status
 from inference.config import get_app_config
 
 _app_config = get_app_config()

apps/gradio-space/src/gradio_space/tabs/education_pptx.py

@@ -1,22 +1,37 @@
+from pathlib import Path
+
 import gradio as gr
 
 from agent.runner import AgentRunner
+from agent.tools.pptx import get_outputs_dir
 from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
 from inference.factory import get_backend
 
+def _error_html(message: str) -> str:
+    safe = (
+        message.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )
+    return (
+        f'<div style="padding:12px;border:1px solid #c44;border-radius:8px;'
+        f'background:#fff5f5;color:#8a1f1f;">{safe}</div>'
+    )
+
+
 def generate_lesson_slides(
     topic: str,
     grade: str,
     slide_count: int,
-) -> tuple[str, str, list[tuple[str, str]], str | None, str | None, str | None, str, str]:
+) -> tuple[str, str, list[str], str | None, str | None, str | None, str, str]:
     model_key = get_active_model_key()
     load_error = ensure_model_loaded(model_key)
     if load_error:
-        return load_error, "", [], None, None, None, load_error, load_error
+        return load_error, _error_html(load_error), [], None, None, None, load_error, load_error
 
     if not topic.strip():
         message = "Please enter a lesson topic."
-        return message, "", [], None, None, None, message, message
+        return message, _error_html(message), [], None, None, None, message, message
 
     try:
         runner = AgentRunner()
@@ -29,9 +44,9 @@ def generate_lesson_slides(
         )
     except Exception as exc:  # noqa: BLE001 — show agent errors in UI
         message = f"Agent error: {exc}"
-        return message, "", [], None, None, None, message, message
+        return message, _error_html(message), [], None, None, None, message, message
 
-    gallery = [(path, f"Slide {i}") for i, path in enumerate(result.preview_images)]
+    gallery = [str(Path(p).resolve()) for p in result.preview_images]
     trace_summary = (
         f"Run `{result.trace.run_id}` · skill `{result.trace.skill}` · "
         f"model `{result.trace.model}`\n\n"
@@ -41,9 +56,9 @@ def generate_lesson_slides(
         result.markdown_preview,
         result.html_preview,
         gallery,
-        result.pptx_path,
-        result.docx_path,
-        result.html_export_path,
+        str(Path(result.pptx_path).resolve()),
+        str(Path(result.docx_path).resolve()),
+        str(Path(result.html_export_path).resolve()),
         trace_summary,
         result.trace.to_json(),
     )
@@ -88,8 +103,9 @@ the agent then builds a downloadable PowerPoint — no cloud LLM API.
             slide_gallery = gr.Gallery(
                 label="Slide thumbnails",
                 columns=2,
-                height="auto",
+                height=420,
                 object_fit="contain",
+                preview=True,
             )
         with gr.Tab("Outline"):
             outline_preview = gr.Markdown(label="Outline (markdown)")
@@ -137,3 +153,9 @@ then choose **Open with → Google Docs**. You can also upload the `.html` file
             trace_box,
         ],
     )
+
+
+def gradio_allowed_paths() -> list[str]:
+    """Paths Gradio must be allowed to read for previews and downloads."""
+    root = get_outputs_dir().resolve()
+    return [str(root)]

libs/agent/src/agent/preview.py

@@ -215,12 +215,17 @@ def _draw_slide_image(
 
     y = margin
     if is_title:
-        draw.text((margin, height // 2 - 80), _wrap_text(title, 28), fill=fg, font=title_font)
+        y_title = height // 2 - 80
+        for part in _wrap_text(title, 28).split("\n"):
+            draw.text((margin, y_title), part, fill=fg, font=title_font)
+            y_title += 64
         if subtitle:
             draw.text((margin, height // 2 + 40), subtitle, fill=accent, font=small_font)
     else:
-        draw.text((margin, y), _wrap_text(title, 32), fill=fg, font=title_font)
-        y += 90
+        for part in _wrap_text(title, 32).split("\n"):
+            draw.text((margin, y), part, fill=fg, font=title_font)
+            y += 52
+        y += 20
         for bullet in bullets:
             line = _wrap_text(f"• {bullet}", 48)
             for part in line.split("\n"):

libs/agent/src/agent/prompts.py

@@ -40,10 +40,19 @@ def education_outline_user(req: EducationPptxInput) -> str:
     )
 
 
-def education_outline_repair(invalid_output: str, error: str) -> str:
+def education_outline_repair(
+    invalid_output: str,
+    error: str,
+    *,
+    expected_slides: int | None = None,
+) -> str:
+    count_line = ""
+    if expected_slides is not None:
+        count_line = f"\nYou must include exactly {expected_slides} items in the slides array.\n"
     return (
         "The previous response was invalid JSON or did not match the schema.\n"
         f"Validation error: {error}\n"
+        f"{count_line}"
         f"Previous output:\n{invalid_output}\n\n"
         "Return corrected JSON only, no explanation."
     )

libs/agent/src/agent/runner.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from inference.base import InferenceBackend
 
-from agent.models import EducationPptxInput, SlideOutline
+from agent.models import EducationPptxInput, SlideOutline, SlideSpec
 from agent.preview import outline_to_html, render_slide_images
 from agent.prompts import (
     education_outline_repair,
@@ -125,34 +125,94 @@ class AgentRunner:
         trace.log_llm(prompt_text, raw)
 
         try:
-            return self._parse_outline(raw, req.slide_count)
+            return self._parse_outline(raw, req.slide_count, trace)
         except (json.JSONDecodeError, ValueError) as first_error:
             repair_messages = messages + [
                 {"role": "assistant", "content": raw},
                 {
                     "role": "user",
-                    "content": education_outline_repair(raw, str(first_error)),
+                    "content": education_outline_repair(
+                        raw, str(first_error), expected_slides=req.slide_count
+                    ),
                 },
             ]
+            repair_prompt = education_outline_repair(
+                raw, str(first_error), expected_slides=req.slide_count
+            )
             repaired = backend.chat(repair_messages, max_tokens=2048, temperature=0.1)
-            trace.log_llm(education_outline_repair(raw, str(first_error)), repaired)
-            return self._parse_outline(repaired, req.slide_count)
+            trace.log_llm(repair_prompt, repaired)
+            return self._parse_outline(repaired, req.slide_count, trace)
 
-    def _parse_outline(self, raw: str, expected_slides: int) -> SlideOutline:
-        data = self._extract_json(raw)
+    def _parse_outline(
+        self,
+        raw: str,
+        expected_slides: int,
+        trace: TraceRecorder | None = None,
+    ) -> SlideOutline:
+        data = self._sanitize_outline_data(self._extract_json(raw))
         outline = SlideOutline.model_validate(data)
-        if len(outline.slides) != expected_slides:
-            if len(outline.slides) > expected_slides:
-                outline = SlideOutline(
-                    title=outline.title,
-                    slides=outline.slides[:expected_slides],
-                )
-            else:
-                raise ValueError(
-                    f"Expected {expected_slides} slides, got {len(outline.slides)}"
-                )
+        original_count = len(outline.slides)
+        outline = self._normalize_slide_count(outline, expected_slides)
+        if trace and original_count != expected_slides:
+            trace.log_note(
+                "Adjusted slide count to match request",
+                requested=expected_slides,
+                model_returned=original_count,
+                final=len(outline.slides),
+            )
         return outline
 
+    @staticmethod
+    def _sanitize_outline_data(data: dict[str, Any]) -> dict[str, Any]:
+        title = str(data.get("title") or "Lesson").strip() or "Lesson"
+        slides_in = data.get("slides") or []
+        slides_out: list[dict[str, Any]] = []
+        for index, slide in enumerate(slides_in):
+            if not isinstance(slide, dict):
+                continue
+            slide_title = str(slide.get("title") or f"Slide {index + 1}").strip()
+            bullets_raw = slide.get("bullets") or []
+            if isinstance(bullets_raw, str):
+                bullets_raw = [bullets_raw]
+            bullets = [str(b).strip() for b in bullets_raw if str(b).strip()]
+            if not bullets:
+                bullets = ["Discuss this topic with the class"]
+            slides_out.append(
+                {
+                    "title": slide_title or f"Slide {index + 1}",
+                    "bullets": bullets,
+                    "speaker_note": str(slide.get("speaker_note") or ""),
+                }
+            )
+        if not slides_out:
+            slides_out.append(
+                {
+                    "title": "Introduction",
+                    "bullets": ["Overview of the topic", "Why it matters"],
+                    "speaker_note": "",
+                }
+            )
+        return {"title": title, "slides": slides_out}
+
+    @staticmethod
+    def _normalize_slide_count(outline: SlideOutline, expected: int) -> SlideOutline:
+        slides = list(outline.slides)
+        if len(slides) > expected:
+            slides = slides[:expected]
+        while len(slides) < expected:
+            number = len(slides) + 1
+            slides.append(
+                SlideSpec(
+                    title=f"More about {outline.title}",
+                    bullets=[
+                        "Key idea to expand in class",
+                        "Question for students",
+                    ],
+                    speaker_note="Add details for this slide during the lesson.",
+                )
+            )
+        return SlideOutline(title=outline.title, slides=slides)
+
     @staticmethod
     def _extract_json(text: str) -> dict[str, Any]:
         cleaned = text.strip()

libs/agent/src/agent/tools/pptx.py

@@ -10,6 +10,11 @@ from pptx.util import Inches, Pt
 from agent.models import SlideOutline
 
 
+def get_outputs_dir() -> Path:
+    """Directory for generated artifacts (pptx, docx, preview images)."""
+    return _outputs_dir()
+
+
 def _outputs_dir() -> Path:
     import os
     import tempfile

libs/agent/src/agent/trace.py

@@ -32,6 +32,9 @@ class TraceRecorder:
             }
         )
 
+    def log_note(self, message: str, **details: Any) -> None:
+        self.steps.append({"type": "note", "message": message, **details})
+
     def log_tool(self, name: str, arguments: dict[str, Any], result: str) -> None:
         self.steps.append(
             {

libs/agent/tests/test_runner.py

@@ -5,6 +5,33 @@ from agent.tools.docx import create_docx, create_html_export
 from agent.tools.pptx import create_pptx
 
 
+def test_parse_outline_pads_when_model_returns_too_few():
+    runner = AgentRunner()
+    raw = (
+        '{"title": "AI Agents", "slides": ['
+        '{"title": "Intro", "bullets": ["What is an agent?"]},'
+        '{"title": "Uses", "bullets": ["Automation"]}'
+        "]}"
+    )
+    outline = runner._parse_outline(raw, expected_slides=5)
+    assert len(outline.slides) == 5
+    assert outline.title == "AI Agents"
+
+
+def test_parse_outline_trims_when_model_returns_too_many():
+    runner = AgentRunner()
+    raw = (
+        '{"title": "Topic", "slides": ['
+        '{"title": "A", "bullets": ["a"]},'
+        '{"title": "B", "bullets": ["b"]},'
+        '{"title": "C", "bullets": ["c"]},'
+        '{"title": "D", "bullets": ["d"]}'
+        "]}"
+    )
+    outline = runner._parse_outline(raw, expected_slides=3)
+    assert len(outline.slides) == 3
+
+
 def test_extract_json_from_fenced_block():
     raw = '```json\n{"title": "T", "slides": [{"title": "S", "bullets": ["a"]}]}\n```'
     data = AgentRunner._extract_json(raw)

uv.lock

@@ -45,7 +45,9 @@ version = "0.1.0"
 source = { editable = "libs/agent" }
 dependencies = [
     { name = "inference" },
+    { name = "pillow" },
     { name = "pydantic" },
+    { name = "python-docx" },
     { name = "python-pptx" },
     { name = "pyyaml" },
 ]
@@ -53,7 +55,9 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "inference", editable = "libs/inference" },
+    { name = "pillow", specifier = ">=10.0.0" },
     { name = "pydantic", specifier = ">=2.0.0" },
+    { name = "python-docx", specifier = ">=1.1.0" },
     { name = "python-pptx", specifier = ">=1.0.0" },
     { name = "pyyaml", specifier = ">=6.0.2" },
 ]
@@ -1324,6 +1328,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" },
 ]
 
+[[package]]
+name = "python-docx"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "lxml" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/f7/eddfe33871520adab45aaa1a71f0402a2252050c14c7e3009446c8f4701c/python_docx-1.2.0.tar.gz", hash = "sha256:7bc9d7b7d8a69c9c02ca09216118c86552704edc23bac179283f2e38f86220ce", size = 5723256, upload-time = "2025-06-16T20:46:27.921Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d0/00/1e03a4989fa5795da308cd774f05b704ace555a70f9bf9d3be057b680bcf/python_docx-1.2.0-py3-none-any.whl", hash = "sha256:3fd478f3250fbbbfd3b94fe1e985955737c145627498896a8a6bf81f4baf66c7", size = 252987, upload-time = "2025-06-16T20:46:22.506Z" },
+]
+
 [[package]]
 name = "python-multipart"
 version = "0.0.32"