feat(creative): add deck_builder skill for deterministic PPTX assembly (#276)

[tusharjamunkar]

Resolves #276

Summary of Changes

Adds the creative/deck_builder skill (v0.1.0) for deterministic, offline assembly of Microsoft PowerPoint (.pptx) presentations from structured JSON deck specifications.

1. Actions:

   • validate_spec (default): Validates deck_spec against strict JSON Schema and flags soft-limit warnings (e.g. text truncations, missing assets) without file I/O. Supports strict=true to fail closed on warnings.
   • render: Assembles slides, applies theme tokens, inserts normalized images/charts, writes editable .pptx to disk. Protected with path traversal checks against unauthorized directory escapes.
   • inspect: Reads an existing .pptx presentation and returns slide counts, titles, layout names, shape counts, and speaker notes presence.
   • list_templates: Enumerates bundled template IDs, names, descriptions, and aspect ratios.

2. 10 Supported Slide Layout Types:

   • title: Cover slide with title, subtitle, optional logo/hero picture, and speaker notes.
   • section: Section header divider.
   • bullets: Standard bullet list with soft-limit truncation warning (BULLET_TRUNCATED for bullets >120 chars).
   • two_column: Side-by-side comparison layout.
   • image: Full or half-bleed graphic with optional title and caption.
   • image_caption: Side-by-side graphic and detailed explanation body.
   • quote: Stylized pull-quote and attribution.
   • table: Tabular data grid with styled headers.
   • chart: Native OpenXML chart (bar, line, pie) with categories and series data.
   • blank: Clean canvas with optional speaker notes.

3. 3 Bundled 16:9 Widescreen Templates:

   • pitch_v1 (default): Modern startup aesthetic with vibrant purple/indigo accent (#6E57E0).
   • corporate_v1: Executive presentation with navy/slate accent (#1E3A8A).
   • minimal_v1: Editorial monochrome aesthetic with charcoal accent (#262626).

4. Asset & Security Hardening:

   • Local path and Base64 image payload support normalized via Pillow.
   • Path traversal defenses on output_path preventing directory traversal sequences.
   • Fail-closed validation for mismatched chart dimensions or table row lengths.

5. Packaging, Documentation & Demos:

   • Declared python-pptx>=1.0.0 and pillow in manifest; added import alias mapping in skillware/core/extras.py; updated optional extras via scripts/sync_extras.py.
   • 5-provider catalog page (docs/skills/deck_builder.md) with Claude, OpenAI, Gemini, DeepSeek, and Ollama snippets.
   • Offline local demo (examples/deck_builder_demo.py) smoke-tested in CI (tests/test_examples_smoke.py).
   • Added [Unreleased] entry to CHANGELOG.md.

Verification

• pytest skills/creative/deck_builder/test_skill.py -v (14 passed)
• pytest tests/skills/creative/test_deck_builder.py -v (2 passed)
• pytest tests/test_card_ui_schema.py -v (18 passed)
• pytest tests/test_registry_docs.py -v (9 passed)
• pytest tests/test_extras_sync.py -v (6 passed)
• pytest tests/test_skill_issuer.py -v (5 passed)
• pytest tests/test_examples_smoke.py -v (11 passed)
• pytest (618 passed, 4 skipped, 0 failures)
• python scripts/sync_extras.py --check (Optional extras sync OK)
• python -m black . && python -m flake8 . (100% clean)
• python examples/deck_builder_demo.py (verified all 4 steps offline)

[rosspeili]

Thanks for the thorough work on this @tusharjamunkar

The multi-action design, JSON Schema validation, bundled templates, offline constitution, tests, catalog page, extras sync, and smoke demo all match what we ask for in CONTRIBUTING and the ai-native workflow. Really nice and clean job <3

This looks merge-ready after rebase onto current main (post-0.5.4). I ran the bundle locally, 16/16 tests passed with python-pptx + pillow, black/flake8 clean on touched files also.

---

Rebase / merge hygiene (required)

Please rebase and resolve conflicts in:

• CHANGELOG.md, add a single [Unreleased] → Added entry for deck_builder only; do not re-add items already shipped in 0.5.4
• docs/usage/agent_loops.md
• examples/README.md
• pyproject.toml
• tests/test_examples_smoke.py

After rebase, fill the Skill history row in docs/skills/deck_builder.md (commit hash, date, 0.1.0, your Github handle).

---

Agent-flow validation (new)

I simulated the intended host-agent loop: NL prompt → agent drafts deck_spec → validate_spec → render → inspect. The flow works as designed with four scenarios (7-slide product pitch, 6-slide corporate technical brief, 5-slide investor update with image, URL-as-path stress test) all validated and rendered successfully! <3

Scenario	Slides	Result
Enterprise product pitch (pitch_v1)	7	✅ clean
Microservices briefing (corporate_v1)	6	✅ clean
Investor update + local image (minimal_v1)	5	✅ clean
Agent passes URL as image.path	2	⚠️ ASSET_NOT_FOUND warning; deck still renders text-only

Overall, any host agent with this bundle can read instructions.md, build valid JSON, and produce editable .pptx files. The recommended workflow (validate_spec → review warnings → render) is sound.

---

Small v1 improvements I'd like before merge with this PR

These are not blockers as per the original issue, but they materially help agents and I think would make this a very tight first version:

1. instructions.md, image handling callout
   Explicitly state: images are path or base64 only, not URLs. If the user provides a URL, the host agent must download to a temp file (or base64-encode) before calling render. Common mistake: putting https://… in image.path → ASSET_NOT_FOUND.

2. instructions.md, minimal worked example
   One full NL prompt → 7-slide deck_spec JSON example (like the issue body) so agents see the mapping from user constraints ("don't include pricing") to slide choices.

3. Chain example: one-line skill chaining pointer on the catalog page, e.g. compose with creative/bg_remover for logos/heroes before render (skill chaining docs). A small bg_remover → deck_builder chain example (local script or YAML chain) would fit the "composable skills" story with 0.5.4 chain tooling.

---

Image strategy (v1 vs v2, for awareness)

For v1, we agree with the offline constitution:

• User attachments → agent writes path or base64
• User URLs → agent downloads outside the skill, then passes local path
• Missing images → warning + text-only slide (current behavior is fine)

For v2 (separate upgrade issue I will create after we merge this, and tag you if you wanna pick it up), we're planning bundled smart placeholders, optional image-gen behind env vars, and a separate stock-image finder skill in a chain, not in v0.1 scope.

---

Overall this is in a very good shape, thank you for the effort. <3
Once rebased and the above ammended, I am keen to land it and close #276, then will open a skill upgrade issue and tag you if you wanna continue this tree.

[tusharjamunkar]

Thanks for the review and validation testing @rosspeili! <3

I have addressed all feedback items:

1. Rebase & Merge Hygiene:

   • Rebased cleanly on latest main (post-0.5.4).
   • Cleaned CHANGELOG.md with a single [Unreleased] → ### Added entry for creative/deck_builder only.
   • Resolved merge points in docs/usage/agent_loops.md, examples/README.md, pyproject.toml, and tests/test_examples_smoke.py.
   • Populated the Skill history table in docs/skills/deck_builder.md with commit hash, date, version 0.1.0, and contributor handle.

2. Image Handling Guidance (instructions.md):

   • Explicitly documented that image.path must be a local file path and image.base64 must be raw base64 string (not remote URLs).
   • Noted that host agents are responsible for downloading remote URLs to local temp files before calling validate_spec or render (avoiding ASSET_NOT_FOUND).

3. Worked Example (instructions.md):

   • Added a full Natural Language Prompt → 7-slide deck_spec JSON mapping (Enterprise product pitch without pricing), demonstrating how user constraints map to slide types (title, section, bullets, two_column, table, quote, CTA).

4. Skill Chaining Example (docs/skills/deck_builder.md):

   • Added a composable chaining guide and code snippet using SkillContext with creative/bg_remover to isolate transparent logos before assembling the presentation.

All 679 repository tests, formatting/linting (black, flake8), extras sync check, and all 6 GitHub Actions CI matrix checks are green!

[rosspeili]

Thanks for the quick turnaround @tusharjamunkar, I took the initiative and pushed a maintainer wrap-up to your branch, rebase onto latest main (CHANGELOG merged with #335), skill history commit fixed (a66e76e), and a small typo in instructions.md. Local deck_builder tests pass. Good to merge when CI is green, thanks again for #276!