skills prompt and tools

libs/agent/src/agent/prompts.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+
+from agent.models import EducationPptxInput
+
+
+def education_outline_system(skill_body: str) -> str:
+    return f"""You are a lesson-planning assistant for teachers.
+Follow the skill workflow below and output ONLY valid JSON (no markdown fences).
+
+Skill workflow:
+{skill_body}
+
+JSON schema:
+{{
+  "title": "string — presentation title",
+  "slides": [
+    {{
+      "title": "string — slide heading",
+      "bullets": ["string", "..."],
+      "speaker_note": "string — one sentence for the teacher"
+    }}
+  ]
+}}
+
+Rules:
+- Use exactly the requested number of content slides (title slide is added separately by the tool).
+- Bullets should be short, age-appropriate, and factual.
+- speaker_note is optional but helpful for each slide.
+"""
+
+
+def education_outline_user(req: EducationPptxInput) -> str:
+    return (
+        f"Topic: {req.topic}\n"
+        f"Grade level: {req.grade}\n"
+        f"Number of content slides: {req.slide_count}\n"
+        "Return JSON only."
+    )
+
+
+def education_outline_repair(invalid_output: str, error: str) -> str:
+    return (
+        "The previous response was invalid JSON or did not match the schema.\n"
+        f"Validation error: {error}\n"
+        f"Previous output:\n{invalid_output}\n\n"
+        "Return corrected JSON only, no explanation."
+    )
+
+
+def outline_to_markdown(title: str, slides: list[dict]) -> str:
+    lines = [f"# {title}", ""]
+    for index, slide in enumerate(slides, start=1):
+        lines.append(f"## Slide {index}: {slide.get('title', 'Untitled')}")
+        for bullet in slide.get("bullets", []):
+            lines.append(f"- {bullet}")
+        note = slide.get("speaker_note", "")
+        if note:
+            lines.append(f"\n*Teacher note:* {note}")
+        lines.append("")
+    return "\n".join(lines).strip()
+
+
+def outline_json_example(slide_count: int) -> str:
+    example = {
+        "title": "Example Lesson",
+        "slides": [
+            {
+                "title": f"Slide {i}",
+                "bullets": ["Key point A", "Key point B"],
+                "speaker_note": "Brief teaching tip.",
+            }
+            for i in range(1, slide_count + 1)
+        ],
+    }
+    return json.dumps(example, indent=2)

libs/agent/src/agent/skills.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass(frozen=True)
+class Skill:
+    name: str
+    description: str
+    task: str
+    tools: list[str]
+    model_hints: list[str]
+    body: str
+    path: Path
+
+
+def _find_skills_root() -> Path | None:
+    import os
+
+    env_path = os.environ.get("SKILLS_DIR")
+    if env_path:
+        root = Path(env_path)
+        if root.is_dir():
+            return root.resolve()
+
+    for base in (Path.cwd(), *Path.cwd().parents):
+        candidate = base / "skills"
+        if candidate.is_dir():
+            return candidate.resolve()
+    return None
+
+
+def _parse_skill_md(path: Path) -> Skill:
+    text = path.read_text()
+    match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", text, re.DOTALL)
+    if not match:
+        raise ValueError(f"{path}: expected YAML frontmatter delimited by ---")
+
+    meta: dict[str, Any] = yaml.safe_load(match.group(1)) or {}
+    body = match.group(2).strip()
+
+    return Skill(
+        name=str(meta.get("name", path.parent.name)),
+        description=str(meta.get("description", "")),
+        task=str(meta.get("task", "")),
+        tools=[str(t) for t in meta.get("tools", [])],
+        model_hints=[str(m) for m in meta.get("model_hints", [])],
+        body=body,
+        path=path,
+    )
+
+
+class SkillRegistry:
+    def __init__(self, skills_root: Path | None = None) -> None:
+        self._root = skills_root or _find_skills_root()
+        self._skills: dict[str, Skill] = {}
+        if self._root is not None:
+            self._load_all()
+
+    @property
+    def root(self) -> Path | None:
+        return self._root
+
+    def _load_all(self) -> None:
+        assert self._root is not None
+        for skill_md in sorted(self._root.glob("*/SKILL.md")):
+            skill = _parse_skill_md(skill_md)
+            self._skills[skill.name] = skill
+
+    def get(self, name: str) -> Skill:
+        if name not in self._skills:
+            known = ", ".join(sorted(self._skills)) or "(none found)"
+            raise KeyError(f"Unknown skill {name!r}. Known: {known}")
+        return self._skills[name]
+
+    def list_by_task(self, task: str) -> list[Skill]:
+        return [s for s in self._skills.values() if s.task == task]
+
+    def all(self) -> list[Skill]:
+        return list(self._skills.values())

libs/agent/src/agent/tools/__init__.py

@@ -0,0 +1,3 @@
+from agent.tools.pptx import create_pptx
+
+__all__ = ["create_pptx"]

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

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import re
+import uuid
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.util import Inches, Pt
+
+from agent.models import SlideOutline
+
+
+def _outputs_dir() -> Path:
+    import os
+    import tempfile
+
+    env = os.environ.get("AGENT_OUTPUTS_DIR")
+    if env:
+        path = Path(env)
+    else:
+        path = Path(tempfile.gettempdir()) / "agent_outputs"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _safe_filename(title: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "_", title.strip().lower()).strip("_")
+    return slug[:60] or "lesson"
+
+
+def create_pptx(outline: SlideOutline, run_id: str | None = None) -> Path:
+    """Build a .pptx from a validated slide outline."""
+    rid = run_id or uuid.uuid4().hex[:12]
+    out_dir = _outputs_dir()
+    filename = f"{_safe_filename(outline.title)}_{rid}.pptx"
+    path = out_dir / filename
+
+    prs = Presentation()
+    prs.slide_width = Inches(10)
+    prs.slide_height = Inches(7.5)
+
+    title_layout = prs.slide_layouts[0]
+    title_slide = prs.slides.add_slide(title_layout)
+    title_slide.shapes.title.text = outline.title
+    if title_slide.placeholders[1].text_frame:
+        title_slide.placeholders[1].text = "Generated lesson slides"
+
+    bullet_layout = prs.slide_layouts[1]
+    for slide_spec in outline.slides:
+        slide = prs.slides.add_slide(bullet_layout)
+        slide.shapes.title.text = slide_spec.title
+        body = slide.placeholders[1].text_frame
+        body.clear()
+        for index, bullet in enumerate(slide_spec.bullets):
+            if index == 0:
+                p = body.paragraphs[0]
+            else:
+                p = body.add_paragraph()
+            p.text = bullet
+            p.level = 0
+            p.font.size = Pt(20)
+        if slide_spec.speaker_note:
+            notes = slide.notes_slide.notes_text_frame
+            notes.text = slide_spec.speaker_note
+
+    prs.save(str(path))
+    return path

libs/agent/src/agent/tools_registry.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from agent.models import SlideOutline
+from agent.tools.pptx import create_pptx
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    name: str
+    description: str
+    handler: Callable[..., Any]
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolSpec] = {}
+        self.register(
+            "create_pptx",
+            "Create a PowerPoint file from a validated SlideOutline",
+            self._handle_create_pptx,
+        )
+
+    def register(self, name: str, description: str, handler: Callable[..., Any]) -> None:
+        self._tools[name] = ToolSpec(name=name, description=description, handler=handler)
+
+    def get(self, name: str) -> ToolSpec:
+        if name not in self._tools:
+            raise KeyError(f"Unknown tool {name!r}")
+        return self._tools[name]
+
+    def _handle_create_pptx(self, outline: SlideOutline, run_id: str | None = None) -> str:
+        path = create_pptx(outline, run_id=run_id)
+        return str(path)