education ppxt skills

.cursor/plans/skill_agent_pptx_5413e3c2.plan.md

@@ -4,13 +4,13 @@ overview: Add a Hermes-style skill agent library on top of your existing Transfo
 todos:
   - id: agent-lib
     content: "Create libs/agent: SkillRegistry, ToolRegistry, AgentRunner, TraceRecorder, pydantic outline models"
-    status: in_progress
+    status: completed
   - id: pptx-skill
     content: Add skills/education-pptx/SKILL.md and create_pptx tool (python-pptx)
-    status: pending
+    status: completed
   - id: gradio-tabs
     content: "Refactor Gradio app into Tabs: Education PPTX (primary) + Chat (debug)"
-    status: pending
+    status: in_progress
   - id: docker-workspace
     content: Wire agent package into uv workspace, Dockerfile, models.yaml active_model
     status: pending

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

@@ -2,103 +2,11 @@ import os
 
 import gradio as gr
 
-from inference.config import get_app_config, get_model_config
-from inference.factory import get_backend, reset_backend
+from gradio_space.model_loading import warmup
+from gradio_space.tabs import build_chat_tab, build_education_pptx_tab
+from inference.config import get_app_config
 
 _app_config = get_app_config()
-_current_model_key: str | None = None
-_load_state: dict[str, bool] = {}
-_load_errors: dict[str, str] = {}
-
-
-def _ensure_model_loaded(model_key: str) -> str | None:
-    global _current_model_key
-
-    if model_key != _current_model_key:
-        reset_backend()
-        _current_model_key = model_key
-
-    if _load_state.get(model_key):
-        return None
-
-    if model_key in _load_errors:
-        return _load_errors[model_key]
-
-    try:
-        get_backend(model_key).load()
-        _load_state[model_key] = True
-        return None
-    except Exception as exc:  # noqa: BLE001 — surface model load failures in the UI
-        message = f"Failed to load model: {exc}"
-        _load_errors[model_key] = message
-        return message
-
-
-def _history_to_messages(history: list) -> list[dict[str, str]]:
-    messages: list[dict[str, str]] = []
-    for item in history:
-        if isinstance(item, dict):
-            messages.append({"role": item["role"], "content": item["content"]})
-        else:
-            user_msg, assistant_msg = item
-            messages.append({"role": "user", "content": user_msg})
-            if assistant_msg:
-                messages.append({"role": "assistant", "content": assistant_msg})
-    return messages
-
-
-def chat(message: str, history: list, model_key: str) -> str:
-    load_error = _ensure_model_loaded(model_key)
-    if load_error:
-        return load_error
-
-    messages = _history_to_messages(history)
-    messages.append({"role": "user", "content": message})
-    return get_backend(model_key).chat(messages)
-
-
-def _runtime_device_hint(model_key: str) -> str:
-    model = get_model_config(model_key)
-    if model.backend == "transformers":
-        try:
-            import torch
-
-            if torch.cuda.is_available():
-                return f"GPU ({torch.cuda.get_device_name(0)})"
-        except ImportError:
-            pass
-        return "CPU"
-    if model.n_gpu_layers > 0:
-        return f"llama.cpp GPU offload ({model.n_gpu_layers} layers)"
-    return "CPU"
-
-
-def warmup(model_key: str | None = None) -> str:
-    key = model_key or _app_config.active_model
-    model = get_model_config(key)
-
-    if _load_state.get(key):
-        backend = get_backend(key)
-        device = (
-            backend.device_label
-            if hasattr(backend, "device_label")
-            else _runtime_device_hint(key)
-        )
-        return f"Model ready: {model.label} on {device}"
-
-    if key in _load_errors:
-        return _load_errors[key]
-
-    device_hint = _runtime_device_hint(key)
-    return (
-        f"Preset `{key}` selected ({model.backend}, {device_hint}). "
-        "Weights load on the first chat message."
-    )
-
-
-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)}"
 
 
 def build_demo() -> gr.Blocks:
@@ -109,14 +17,14 @@ def build_demo() -> gr.Blocks:
         else "Using built-in presets (models.yaml not found)."
     )
 
-    with gr.Blocks(title="Small Model Hackathon") as demo:
+    with gr.Blocks(title="Lesson Agent — Build Small Hackathon") as demo:
         gr.Markdown(
             f"""
-# Small Model Chat
+# Lesson Agent
 
-Local inference with preset-based configuration.
+Local skill-based agent for teachers — **topic in, PowerPoint out**.
 
-- **Default preset:** `{active.key}` — {active.label}
+- **Model:** `{active.key}` — {active.label}
 - **Backend:** `{active.backend}`
 - {presets_note}
 
@@ -124,36 +32,13 @@ Part of the [Build Small Hackathon](https://huggingface.co/build-small-hackathon
 """
         )
 
-        if _app_config.allow_model_switch and len(_app_config.models) > 1:
-            model_dropdown = gr.Dropdown(
-                choices=_app_config.model_choices(),
-                value=_app_config.active_model,
-                label="Model preset",
-                info="Switch presets for local testing. Each preset loads on first use.",
-            )
-            status = gr.Markdown(model_status(_app_config.active_model))
-
-            model_dropdown.change(
-                fn=model_status,
-                inputs=model_dropdown,
-                outputs=status,
-            )
-
-            gr.ChatInterface(
-                fn=chat,
-                additional_inputs=[model_dropdown],
-                examples=[
-                    ["Hello! What can you help me with?", _app_config.active_model],
-                    ["Explain llama.cpp in one sentence.", _app_config.active_model],
-                ],
-            )
-        else:
-            status = gr.Markdown(model_status(_app_config.active_model))
-            gr.ChatInterface(
-                fn=lambda message, history: chat(message, history, _app_config.active_model),
-                examples=["Hello! What can you help me with?", "Explain llama.cpp in one sentence."],
-            )
-            demo.load(lambda: warmup(_app_config.active_model), outputs=status)
+        with gr.Tabs():
+            with gr.Tab("Lesson slides"):
+                build_education_pptx_tab()
+            with gr.Tab("Chat (debug)"):
+                build_chat_tab()
+
+        demo.load(lambda: warmup(_app_config.active_model))
 
     return demo
 

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

@@ -0,0 +1,78 @@
+from inference.config import get_app_config, get_model_config
+from inference.factory import get_backend, reset_backend
+
+_app_config = get_app_config()
+_current_model_key: str | None = None
+_load_state: dict[str, bool] = {}
+_load_errors: dict[str, str] = {}
+
+
+def get_active_model_key() -> str:
+    return _app_config.active_model
+
+
+def ensure_model_loaded(model_key: str) -> str | None:
+    global _current_model_key
+
+    if model_key != _current_model_key:
+        reset_backend()
+        _current_model_key = model_key
+
+    if _load_state.get(model_key):
+        return None
+
+    if model_key in _load_errors:
+        return _load_errors[model_key]
+
+    try:
+        get_backend(model_key).load()
+        _load_state[model_key] = True
+        return None
+    except Exception as exc:  # noqa: BLE001 — surface model load failures in the UI
+        message = f"Failed to load model: {exc}"
+        _load_errors[model_key] = message
+        return message
+
+
+def runtime_device_hint(model_key: str) -> str:
+    model = get_model_config(model_key)
+    if model.backend == "transformers":
+        try:
+            import torch
+
+            if torch.cuda.is_available():
+                return f"GPU ({torch.cuda.get_device_name(0)})"
+        except ImportError:
+            pass
+        return "CPU"
+    if model.n_gpu_layers > 0:
+        return f"llama.cpp GPU offload ({model.n_gpu_layers} layers)"
+    return "CPU"
+
+
+def warmup(model_key: str | None = None) -> str:
+    key = model_key or _app_config.active_model
+    model = get_model_config(key)
+
+    if _load_state.get(key):
+        backend = get_backend(key)
+        device = (
+            backend.device_label
+            if hasattr(backend, "device_label")
+            else runtime_device_hint(key)
+        )
+        return f"Model ready: {model.label} on {device}"
+
+    if key in _load_errors:
+        return _load_errors[key]
+
+    device_hint = runtime_device_hint(key)
+    return (
+        f"Preset `{key}` selected ({model.backend}, {device_hint}). "
+        "Weights load on the first request."
+    )
+
+
+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/__init__.py

@@ -0,0 +1,4 @@
+from gradio_space.tabs.chat import build_chat_tab
+from gradio_space.tabs.education_pptx import build_education_pptx_tab
+
+__all__ = ["build_chat_tab", "build_education_pptx_tab"]

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

@@ -0,0 +1,71 @@
+import gradio as gr
+
+from gradio_space.model_loading import (
+    chat as chat_fn,
+    ensure_model_loaded,
+    get_active_model_key,
+    model_status,
+    warmup,
+)
+from inference.config import get_app_config
+
+_app_config = get_app_config()
+
+
+def _history_to_messages(history: list) -> list[dict[str, str]]:
+    messages: list[dict[str, str]] = []
+    for item in history:
+        if isinstance(item, dict):
+            messages.append({"role": item["role"], "content": item["content"]})
+        else:
+            user_msg, assistant_msg = item
+            messages.append({"role": "user", "content": user_msg})
+            if assistant_msg:
+                messages.append({"role": "assistant", "content": assistant_msg})
+    return messages
+
+
+def chat(message: str, history: list, model_key: str) -> str:
+    load_error = ensure_model_loaded(model_key)
+    if load_error:
+        return load_error
+    return chat_fn(message, history, model_key)
+
+
+def build_chat_tab() -> None:
+    gr.Markdown(
+        """
+### Model chat (debug)
+
+Test the active local model with a simple chat interface.
+"""
+    )
+
+    model_key = get_active_model_key()
+
+    if _app_config.allow_model_switch and len(_app_config.models) > 1:
+        model_dropdown = gr.Dropdown(
+            choices=_app_config.model_choices(),
+            value=_app_config.active_model,
+            label="Model preset",
+        )
+        status = gr.Markdown(model_status(model_key))
+        model_dropdown.change(fn=model_status, inputs=model_dropdown, outputs=status)
+        gr.ChatInterface(
+            fn=chat,
+            additional_inputs=[model_dropdown],
+            examples=[
+                ["Hello! What can you help me with?", _app_config.active_model],
+                ["Explain photosynthesis in one sentence.", _app_config.active_model],
+            ],
+        )
+    else:
+        status = gr.Markdown(model_status(model_key))
+        gr.ChatInterface(
+            fn=lambda message, history: chat(message, history, model_key),
+            examples=[
+                "Hello! What can you help me with?",
+                "Explain photosynthesis in one sentence.",
+            ],
+        )
+        gr.on(fn=lambda: warmup(model_key), outputs=status)

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

@@ -0,0 +1,92 @@
+import gradio as gr
+
+from agent.runner import AgentRunner
+from gradio_space.model_loading import ensure_model_loaded, get_active_model_key, model_status
+from inference.factory import get_backend
+
+
+def generate_lesson_slides(
+    topic: str,
+    grade: str,
+    slide_count: int,
+) -> tuple[str, str | None, str, str]:
+    model_key = get_active_model_key()
+    load_error = ensure_model_loaded(model_key)
+    if load_error:
+        return load_error, None, "", load_error
+
+    if not topic.strip():
+        message = "Please enter a lesson topic."
+        return message, None, "", message
+
+    try:
+        runner = AgentRunner()
+        result = runner.run_education_pptx(
+            topic=topic,
+            grade=grade,
+            slide_count=int(slide_count),
+            model_key=model_key,
+            backend=get_backend(model_key),
+        )
+    except Exception as exc:  # noqa: BLE001 — show agent errors in UI
+        message = f"Agent error: {exc}"
+        return message, None, "", message
+
+    trace_summary = (
+        f"Run `{result.trace.run_id}` · skill `{result.trace.skill}` · "
+        f"model `{result.trace.model}`\n\n"
+        f"Trace saved: `{result.trace_path}`"
+    )
+    return result.markdown_preview, result.pptx_path, trace_summary, result.trace.to_json()
+
+
+def build_education_pptx_tab() -> None:
+    model_key = get_active_model_key()
+
+    gr.Markdown(
+        """
+### Lesson slide builder
+
+Enter a topic and grade level. A **local small model** drafts the outline;
+the agent then builds a downloadable PowerPoint — no cloud LLM API.
+"""
+    )
+    gr.Markdown(model_status(model_key))
+
+    with gr.Row():
+        topic = gr.Textbox(
+            label="Lesson topic",
+            placeholder="e.g. Photosynthesis, Fractions, The water cycle",
+        )
+        grade = gr.Dropdown(
+            label="Grade level",
+            choices=["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "Adult"],
+            value="6",
+        )
+        slide_count = gr.Slider(
+            minimum=3,
+            maximum=8,
+            step=1,
+            value=5,
+            label="Content slides",
+        )
+
+    generate_btn = gr.Button("Generate lesson slides", variant="primary")
+
+    outline_preview = gr.Markdown(label="Outline preview")
+    pptx_file = gr.File(label="Download PowerPoint", interactive=False)
+    trace_box = gr.Textbox(
+        label="Agent trace (JSON)",
+        lines=12,
+        max_lines=20,
+        interactive=False,
+    )
+
+    with gr.Accordion("Trace summary", open=False):
+        trace_summary = gr.Markdown()
+
+    generate_btn.click(
+        fn=generate_lesson_slides,
+        inputs=[topic, grade, slide_count],
+        outputs=[outline_preview, pptx_file, trace_summary, trace_box],
+    )

libs/agent/src/agent/runner.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from inference.base import InferenceBackend
+
+from agent.models import EducationPptxInput, SlideOutline
+from agent.prompts import (
+    education_outline_repair,
+    education_outline_system,
+    education_outline_user,
+    outline_to_markdown,
+)
+from agent.skills import SkillRegistry
+from agent.tools_registry import ToolRegistry
+from agent.trace import TraceRecorder
+
+EDUCATION_PPTX_SKILL = "education-pptx"
+
+
+@dataclass
+class AgentResult:
+    markdown_preview: str
+    pptx_path: str
+    trace: TraceRecorder
+    trace_path: str
+    outline: SlideOutline
+
+
+class AgentRunner:
+    def __init__(
+        self,
+        skills: SkillRegistry | None = None,
+        tools: ToolRegistry | None = None,
+    ) -> None:
+        self._skills = skills or SkillRegistry()
+        self._tools = tools or ToolRegistry()
+
+    def run_education_pptx(
+        self,
+        *,
+        topic: str,
+        grade: str,
+        slide_count: int,
+        model_key: str,
+        backend: InferenceBackend,
+    ) -> AgentResult:
+        skill = self._skills.get(EDUCATION_PPTX_SKILL)
+        req = EducationPptxInput(topic=topic.strip(), grade=grade, slide_count=slide_count)
+
+        trace = TraceRecorder(
+            skill=skill.name,
+            model=model_key,
+            user_input=req.model_dump(),
+        )
+
+        backend.load()
+        outline = self._generate_outline(skill, req, backend, trace)
+        tool = self._tools.get("create_pptx")
+        pptx_path = tool.handler(outline, run_id=trace.run_id)
+        trace.log_tool(
+            "create_pptx",
+            {"title": outline.title, "slide_count": len(outline.slides)},
+            pptx_path,
+        )
+        trace.set_artifact(pptx_path)
+
+        slides_dicts = [s.model_dump() for s in outline.slides]
+        markdown = outline_to_markdown(outline.title, slides_dicts)
+        trace_path = trace.save()
+
+        return AgentResult(
+            markdown_preview=markdown,
+            pptx_path=pptx_path,
+            trace=trace,
+            trace_path=str(trace_path),
+            outline=outline,
+        )
+
+    def _generate_outline(
+        self,
+        skill: Any,
+        req: EducationPptxInput,
+        backend: InferenceBackend,
+        trace: TraceRecorder,
+    ) -> SlideOutline:
+        system = education_outline_system(skill.body)
+        user = education_outline_user(req)
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        prompt_text = system + "\n\n" + user
+        raw = backend.chat(messages, max_tokens=2048, temperature=0.3)
+        trace.log_llm(prompt_text, raw)
+
+        try:
+            return self._parse_outline(raw, req.slide_count)
+        except (json.JSONDecodeError, ValueError) as first_error:
+            repair_messages = messages + [
+                {"role": "assistant", "content": raw},
+                {
+                    "role": "user",
+                    "content": education_outline_repair(raw, str(first_error)),
+                },
+            ]
+            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)
+
+    def _parse_outline(self, raw: str, expected_slides: int) -> SlideOutline:
+        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)}"
+                )
+        return outline
+
+    @staticmethod
+    def _extract_json(text: str) -> dict[str, Any]:
+        cleaned = text.strip()
+        fence = re.search(r"```(?:json)?\s*(\{.*\})\s*```", cleaned, re.DOTALL)
+        if fence:
+            cleaned = fence.group(1)
+        else:
+            start = cleaned.find("{")
+            end = cleaned.rfind("}")
+            if start >= 0 and end > start:
+                cleaned = cleaned[start : end + 1]
+        return json.loads(cleaned)

skills/education-pptx/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: education-pptx
+description: Create a short lesson PowerPoint from a topic and grade level
+task: education
+tools:
+  - create_pptx
+model_hints:
+  - minicpm5-1b
+  - qwen3b-gguf
+---
+
+## Workflow
+
+1. Ask for topic, audience grade, and slide count (3–8 content slides).
+2. Produce a JSON outline with `title` and `slides` (each slide has `title`, `bullets`, `speaker_note`).
+3. Call `create_pptx` with the validated outline.
+4. Return a download link and markdown preview for the teacher.