@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/office-artifacts/references/powerpoint/GUIDE.md

@@ -0,0 +1,220 @@
+---
+name: powerpoint
+description: Create, read, edit .pptx decks with python-pptx.
+version: 1.1.0
+author: Nous Research
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [pptx, powerpoint, presentations, slides, office, python-pptx]
+    category: productivity
+    related_skills: [docx, xlsx, pdf]
+---
+
+# Powerpoint Skill
+
+Create, inspect, and edit PowerPoint (.pptx) presentations using the
+python-pptx library. Five helper scripts cover deck creation from a JSON
+spec, structured read-back, in-place edits, template-driven brand decks,
+and slide rendering — all offline, no PowerPoint installation required.
+
+## When to Use
+
+- The user asks to build a slide deck, report presentation, or pitch deck.
+- You need to extract text, notes, tables, chart data, or images from a
+  .pptx someone shared.
+- You need to update an existing deck: replace text, refresh or patch
+  chart data, swap a logo, duplicate/remove/reorder slides, set
+  backgrounds, footers, hyperlinks, or speaker notes.
+- You must produce an on-brand deck from a company .pptx template.
+- Do NOT use this for .ppt (legacy binary) files — convert them first with
+  `soffice --convert-to pptx old.ppt` if LibreOffice is available.
+
+## Prerequisites
+
+- Python 3.10+ with `python-pptx` installed
+  (`pip install python-pptx`).
+- Optional: LibreOffice (`soffice`) plus poppler (`pdftoppm` or
+  `pdftocairo`) for rendering slides to PNGs and for PDF export.
+  `pptx_render.py` detects both with `shutil.which` and degrades
+  gracefully (reports `{"rendered": false, "missing": [...]}`, exit 0)
+  when absent — all create/read/edit operations work without them.
+- Check availability via `terminal`:
+  `python -c "import pptx; print(pptx.__version__)"` and `which soffice pdftoppm`.
+
+## How to Run
+
+All scripts live in `scripts/`, take `--help`, print JSON to stdout, and
+exit non-zero on failure. Run them with `terminal`:
+
+```bash
+python scripts/pptx_create.py deck.json out.pptx
+python scripts/pptx_read.py deck.pptx --outline      # full JSON outline
+python scripts/pptx_read.py deck.pptx --notes        # speaker notes
+python scripts/pptx_read.py deck.pptx --images ./img # export pictures
+python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp"
+python scripts/pptx_edit.py deck.pptx --chart-data update.json
+python scripts/pptx_edit.py deck.pptx --duplicate-slide 2
+python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0
+python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json
+python scripts/pptx_render.py deck.pptx --outdir ./render  # slide PNGs
+```
+
+Author JSON specs with `write_file`; inspect script output and generated
+JSON with `read_file`.
+
+## Quick Reference
+
+| Task | Command |
+|---|---|
+| New deck from spec | `pptx_create.py spec.json out.pptx` |
+| 16:9 vs 4:3 | `"slide_size": "16:9"` or `"4:3"` in the spec |
+| Outline as JSON | `pptx_read.py deck.pptx --outline` |
+| Export images | `pptx_read.py deck.pptx --images DIR` |
+| Replace text | `pptx_edit.py deck.pptx --replace-text OLD NEW` |
+| Replace chart data | `pptx_edit.py deck.pptx --chart-data spec.json` |
+| Patch one series | same flag, spec with `"ops"` (see below) |
+| Swap picture | `pptx_edit.py deck.pptx --swap-image N NAME new.png` |
+| Duplicate slide | `pptx_edit.py deck.pptx --duplicate-slide N` |
+| Remove slide | `pptx_edit.py deck.pptx --remove-slide N` |
+| Reorder slide | `pptx_edit.py deck.pptx --move-slide FROM TO` |
+| Slide background | `pptx_edit.py deck.pptx --set-background N RRGGBB` |
+| Hyperlink runs | `pptx_edit.py deck.pptx --hyperlink N TEXT URL` |
+| Slide number on | `pptx_edit.py deck.pptx --enable-slide-number N` |
+| Footer text | `pptx_edit.py deck.pptx --set-footer N TEXT` |
+| Set notes | `pptx_edit.py deck.pptx --set-notes N TEXT` |
+| Append notes | `pptx_edit.py deck.pptx --append-notes N TEXT` |
+| Fill template | `pptx_from_template.py tpl.pptx out.pptx --values v.json` |
+| Render slide PNGs | `pptx_render.py deck.pptx --outdir DIR` |
+
+## Procedure
+
+### 1. Create a deck
+
+Write a JSON spec (see `pptx_create.py --help` for the full format), then
+run `pptx_create.py`. Per slide you can set: `layout` (title,
+title_content, section, two_content, title_only, blank), `title`,
+`subtitle`, `bullets` (strings, or dicts with `level` 0-4, `size` pt,
+`bold`, `italic`, `font`, `color` hex, `link` URL for a hyperlink),
+`background` (solid hex), `footer` (text; enables the layout's footer
+placeholder), `slide_number` (true; enables the layout's slide-number
+placeholder), `images` (path + left/top/width/height in inches), `tables`
+(`rows` as list-of-lists), `shapes` (rectangle, rounded_rectangle, oval,
+diamond, right_arrow, chevron, with `fill` hex + optional `text`),
+`charts` (bar, bar_h, line, pie with `categories` + `series`), and
+`notes` (speaker notes).
+
+### 2. Read a deck
+
+`pptx_read.py deck.pptx --outline` returns slide size, layout inventory,
+and per slide: layout name, all shape texts, table cells, image inventory
+(filename/ext/bytes), chart categories/series/values, and speaker notes.
+Use `--images DIR` to dump embedded pictures to files, then
+`vision_analyze` on any exported image if you need to see its content.
+
+### 3. Edit a deck
+
+`pptx_edit.py` combines operations in one pass; use `--output` to keep the
+original. Text replacement scans slide shapes, table cells, and notes.
+Image swap retargets the picture's relationship id so position and size
+are preserved. Slide removal drops the relationship and the `<p:sldId>`
+entry; reorder moves the `<p:sldId>` element within `<p:sldIdLst>`
+(python-pptx has no public API for either — the script does the XML-level
+work). `--duplicate-slide N` appends an independent deep copy of slide N:
+shape XML plus image/media/hyperlink relationships are cloned and rIds
+remapped, so editing the copy never touches the original. Chart slides
+are refused (see Pitfalls). `--set-notes`/`--append-notes` edit speaker
+notes; `--set-background`, `--hyperlink`, `--enable-slide-number`, and
+`--set-footer` handle deck polish.
+
+Chart updates take a JSON spec via `--chart-data`. Full replace:
+`{"slide": 0, "chart": 0, "categories": [...], "series": {...}}`. For
+surgical edits, pass `"ops"` instead — a list of
+`{"op": "update_series", "name": ..., "values": [...]}`,
+`add_series`, `remove_series`, `rename_category` (`from`/`to` or
+`index`), and `set_title`. python-pptx can only swap a chart's entire
+dataset (`replace_data`), so ops are implemented as read-existing →
+modify → replace; the per-part UX is a wrapper, and any chart data not
+expressible as categories + numeric series will be normalized by the
+round-trip.
+
+### 4. Build from a template
+
+`pptx_from_template.py` opens a brand .pptx, replaces every
+`{{token}}` from a values JSON across slides/tables/notes, and can append
+new slides that use the template's own layouts (by layout name or index)
+so they inherit the master's fonts and colors. Tip: to start from a
+template with zero slides, delete existing ones afterward with
+`pptx_edit.py --remove-slide`.
+
+### 5. Visual verification
+
+`pptx_render.py deck.pptx --outdir ./render` converts the deck to PDF
+with `soffice --headless` and splits it into one PNG per slide with
+`pdftoppm` (or `pdftocairo`). Output JSON lists the PNG paths — review
+each with `vision_analyze`. When either tool is missing the script exits
+0 with `{"rendered": false, "missing": [...]}` and guidance; fall back to
+the JSON outline from `pptx_read.py`, which verifies content and
+structure, just not visuals.
+
+## Converting to PDF
+
+If LibreOffice is installed, export the finished deck to PDF directly:
+
+```bash
+soffice --headless --convert-to pdf --outdir ./out deck.pptx
+```
+
+The output lands at `./out/deck.pdf`. Fonts not installed on the host are
+substituted, so render-verify (Procedure step 5) before shipping the PDF.
+There is no offline pure-Python .pptx→PDF path; if `soffice` is absent,
+say so rather than approximating.
+
+## Pitfalls
+
+- **Run splitting**: PowerPoint fragments paragraph text into runs at
+  spell-check and edit boundaries. `--replace-text` first merges adjacent
+  runs whose formatting is identical, so matches split across such runs
+  are replaced with formatting fully preserved. Only when a match spans
+  *genuinely differently-formatted* runs is the paragraph rewritten with
+  the first run's formatting — verify those slides after replacement.
+- **Chart slides cannot be duplicated**: each chart relationship embeds a
+  separate XLSX workbook part; cloning that graph reliably is not
+  supported, so `--duplicate-slide` refuses chart slides cleanly instead
+  of corrupting the deck. Rebuild the chart on a new slide instead.
+  External-hyperlink and image/media rels are carried over; layout and
+  notes rels are recreated fresh.
+- **Chart ops are a wrapper**: python-pptx replaces the whole dataset;
+  `"ops"` round-trips existing plot data through `replace_data`, and
+  changing chart *type* is not possible.
+- **Reordering is XML-level**: python-pptx has no supported reorder API.
+  `--move-slide` manipulates `<p:sldIdLst>` directly; safe for ordinary
+  decks but re-read the deck afterward to confirm.
+- **Copying slides between decks is unsupported** — duplication works
+  only within one deck, where layouts and masters are shared.
+- Footer/slide-number enablement copies the placeholder from the slide's
+  layout; on layouts without those placeholders, `--set-footer` fails
+  with a clear message (add a textbox instead).
+- Hyperlinks apply to whole runs; `--hyperlink` links every run
+  containing the given text on that slide.
+- The default python-pptx template is 4:3; the create script sets 16:9
+  unless the spec says otherwise. Custom templates keep their own size.
+- Layout indexes vary by template. For brand templates, list layout names
+  first: `pptx_read.py template.pptx --outline` (`layouts_available`).
+- `slide.shapes.title` is None on blank layouts — the create script
+  handles this, but remember it when writing ad-hoc python-pptx code.
+- Always pass `encoding="utf-8"` when writing spec files; tokens like
+  `{{city}}` may be filled with non-ASCII values.
+
+## Verification
+
+1. After any create/edit, run `pptx_read.py OUT.pptx --outline` and check
+   slide count, texts, tables, notes, and chart values match intent.
+2. `--images DIR` then file-size check confirms pictures embedded.
+3. Render every slide with `pptx_render.py deck.pptx --outdir ./render`
+   and review each PNG with `vision_analyze` — this catches overlapping
+   shapes, truncated text, and color problems the outline cannot. If the
+   render tools are missing, the script says so; rely on the outline.
+4. The bundled test suite is the full contract:
+   `python -m pytest tests/ -q` (requires python-pptx + pytest).

package/built-in-skills/office-artifacts/references/powerpoint/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/built-in-skills/office-artifacts/references/powerpoint/NOTICE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/built-in-skills/office-artifacts/references/powerpoint/scripts/pptx_create.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+"""Create a .pptx presentation from a JSON deck spec.
+
+Spec format (all positions/sizes in inches, colors as RRGGBB hex):
+{
+  "slide_size": "16:9",              // or "4:3" (default "16:9")
+  "slides": [
+    {"layout": "title", "title": "My Deck", "subtitle": "Q3 review"},
+    {"layout": "title_content", "title": "Agenda",
+     "bullets": ["Top item",
+                 {"text": "Sub item", "level": 1, "bold": true,
+                  "size": 18, "color": "CC0000", "font": "Arial",
+                  "italic": false,
+                  "link": "https://example.com/agenda"}],
+     "background": "1F2937",           // solid slide background (hex)
+     "footer": "Confidential",         // footer placeholder text
+     "slide_number": true,             // enable slide-number placeholder
+     "notes": "Speaker notes for this slide"},
+    {"layout": "blank", "title": "Widgets",
+     "images":  [{"path": "logo.png", "left": 1, "top": 1, "width": 3}],
+     "tables":  [{"left": 1, "top": 2, "width": 6, "height": 2,
+                  "rows": [["H1", "H2"], ["a", "b"]]}],
+     "shapes":  [{"type": "rounded_rectangle", "left": 8, "top": 1,
+                  "width": 3, "height": 1, "fill": "4472C4",
+                  "text": "Callout", "text_color": "FFFFFF"}],
+     "charts":  [{"type": "bar", "left": 1, "top": 3, "width": 6,
+                  "height": 3.5, "title": "Sales",
+                  "categories": ["Q1", "Q2"],
+                  "series": {"North": [10, 20], "South": [7, 13]}}]}
+  ]
+}
+Layouts: title, title_content, section, two_content, title_only, blank
+Chart types: bar, bar_h, line, pie   Shape types: rectangle,
+rounded_rectangle, oval, diamond, right_arrow, chevron
+"""
+import argparse
+import copy
+import json
+import sys
+
+from pptx import Presentation
+from pptx.chart.data import CategoryChartData
+from pptx.dml.color import RGBColor
+from pptx.enum.chart import XL_CHART_TYPE
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.util import Inches, Pt
+
+LAYOUTS = {"title": 0, "title_content": 1, "section": 2,
+           "two_content": 3, "title_only": 5, "blank": 6}
+CHART_TYPES = {"bar": XL_CHART_TYPE.COLUMN_CLUSTERED,
+               "bar_h": XL_CHART_TYPE.BAR_CLUSTERED,
+               "line": XL_CHART_TYPE.LINE_MARKERS,
+               "pie": XL_CHART_TYPE.PIE}
+SHAPE_TYPES = {"rectangle": MSO_SHAPE.RECTANGLE,
+               "rounded_rectangle": MSO_SHAPE.ROUNDED_RECTANGLE,
+               "oval": MSO_SHAPE.OVAL, "diamond": MSO_SHAPE.DIAMOND,
+               "right_arrow": MSO_SHAPE.RIGHT_ARROW,
+               "chevron": MSO_SHAPE.CHEVRON}
+
+
+def style_run(run, spec):
+    """Apply font styling from a bullet/text spec dict to a run."""
+    font = run.font
+    if spec.get("size"):
+        font.size = Pt(spec["size"])
+    if spec.get("bold") is not None:
+        font.bold = spec["bold"]
+    if spec.get("italic") is not None:
+        font.italic = spec["italic"]
+    if spec.get("font"):
+        font.name = spec["font"]
+    if spec.get("color"):
+        font.color.rgb = RGBColor.from_string(spec["color"])
+    if spec.get("link"):
+        run.hyperlink.address = spec["link"]
+
+
+def add_bullets(text_frame, bullets):
+    text_frame.clear()
+    for i, item in enumerate(bullets):
+        if isinstance(item, str):
+            item = {"text": item}
+        para = text_frame.paragraphs[0] if i == 0 else text_frame.add_paragraph()
+        para.level = int(item.get("level", 0))
+        run = para.add_run()
+        run.text = item.get("text", "")
+        style_run(run, item)
+
+
+def copy_layout_placeholder(slide, ph_idx):
+    """Copy a layout placeholder (footer=11, slide number=12) onto the
+    slide so it actually renders; returns the shape or None if the layout
+    does not provide it."""
+    for ph in slide.slide_layout.placeholders:
+        if ph.placeholder_format.idx == ph_idx:
+            slide.shapes._spTree.append(copy.deepcopy(ph._element))
+            for shape in slide.placeholders:
+                if shape.placeholder_format.idx == ph_idx:
+                    return shape
+    return None
+
+
+def build_slide(prs, spec):
+    layout_idx = LAYOUTS.get(spec.get("layout", "title_content"), 1)
+    slide = prs.slides.add_slide(prs.slide_layouts[layout_idx])
+
+    if spec.get("background"):
+        fill = slide.background.fill
+        fill.solid()
+        fill.fore_color.rgb = RGBColor.from_string(spec["background"])
+    if spec.get("slide_number"):
+        copy_layout_placeholder(slide, 12)
+    if spec.get("footer"):
+        shape = copy_layout_placeholder(slide, 11)
+        if shape is not None:
+            shape.text_frame.text = spec["footer"]
+
+    if spec.get("title") is not None and slide.shapes.title is not None:
+        slide.shapes.title.text = spec["title"]
+    if spec.get("subtitle") is not None:
+        for ph in slide.placeholders:
+            if ph.placeholder_format.idx == 1:
+                ph.text = spec["subtitle"]
+                break
+    if spec.get("bullets"):
+        body = next((ph for ph in slide.placeholders
+                     if ph.placeholder_format.idx != 0), None)
+        if body is None:
+            body = slide.shapes.add_textbox(Inches(0.5), Inches(1.5),
+                                            Inches(9), Inches(5))
+        add_bullets(body.text_frame, spec["bullets"])
+
+    for img in spec.get("images", []):
+        kwargs = {}
+        if img.get("width"):
+            kwargs["width"] = Inches(img["width"])
+        if img.get("height"):
+            kwargs["height"] = Inches(img["height"])
+        slide.shapes.add_picture(img["path"], Inches(img.get("left", 1)),
+                                 Inches(img.get("top", 1)), **kwargs)
+
+    for tbl in spec.get("tables", []):
+        rows = tbl["rows"]
+        shape = slide.shapes.add_table(
+            len(rows), len(rows[0]), Inches(tbl.get("left", 1)),
+            Inches(tbl.get("top", 2)), Inches(tbl.get("width", 6)),
+            Inches(tbl.get("height", 2)))
+        for r, row in enumerate(rows):
+            for c, val in enumerate(row):
+                shape.table.cell(r, c).text = str(val)
+
+    for shp in spec.get("shapes", []):
+        shape = slide.shapes.add_shape(
+            SHAPE_TYPES.get(shp.get("type", "rectangle"), MSO_SHAPE.RECTANGLE),
+            Inches(shp.get("left", 1)), Inches(shp.get("top", 1)),
+            Inches(shp.get("width", 2)), Inches(shp.get("height", 1)))
+        if shp.get("fill"):
+            shape.fill.solid()
+            shape.fill.fore_color.rgb = RGBColor.from_string(shp["fill"])
+        if shp.get("text"):
+            shape.text_frame.text = shp["text"]
+            if shp.get("text_color"):
+                run = shape.text_frame.paragraphs[0].runs[0]
+                run.font.color.rgb = RGBColor.from_string(shp["text_color"])
+
+    for cht in spec.get("charts", []):
+        data = CategoryChartData()
+        data.categories = cht["categories"]
+        for name, values in cht["series"].items():
+            data.add_series(name, values)
+        frame = slide.shapes.add_chart(
+            CHART_TYPES.get(cht.get("type", "bar"),
+                            XL_CHART_TYPE.COLUMN_CLUSTERED),
+            Inches(cht.get("left", 1)), Inches(cht.get("top", 2)),
+            Inches(cht.get("width", 6)), Inches(cht.get("height", 4)), data)
+        if cht.get("title"):
+            frame.chart.has_title = True
+            frame.chart.chart_title.text_frame.text = cht["title"]
+
+    if spec.get("notes"):
+        slide.notes_slide.notes_text_frame.text = spec["notes"]
+    return slide
+
+
+def main(argv=None):
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    parser = argparse.ArgumentParser(
+        description="Create a .pptx deck from a JSON spec.",
+        epilog=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("spec", help="path to JSON deck spec")
+    parser.add_argument("output", help="output .pptx path")
+    args = parser.parse_args(argv)
+
+    with open(args.spec, encoding="utf-8") as fh:
+        spec = json.load(fh)
+
+    prs = Presentation()
+    if spec.get("slide_size", "16:9") == "16:9":
+        prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+    else:
+        prs.slide_width, prs.slide_height = Inches(10), Inches(7.5)
+
+    for slide_spec in spec.get("slides", []):
+        build_slide(prs, slide_spec)
+
+    prs.save(args.output)
+    print(json.dumps({"ok": True, "output": args.output,
+                      "slides": len(prs.slides._sldIdLst)}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())