sonesta — deterministic PowerPoint deck builder from JSON specs

sonesta builds PowerPoint decks from JSON presentation specs, slide specs, assets, themes, templates, and element definitions. The agent uses it when the user needs a reproducible slide deliverable with managed text, images, shapes, tables, charts, notes, and layout validation.

When to use this

• The deliverable is a .pptx deck rather than a markdown report or Excel workbook.
• Slides can be represented as JSON specs with stable IDs and reusable assets.
• The user wants deterministic regeneration after analysis changes.
• Layout, themes, templates, and assets should be validated before rendering.

When this is a stretch (and how to adapt)

• The user wants freeform slide design. Use sonesta for structured final decks after the story and layout stabilize.
• The deck contains complex custom visuals. Generate those as image assets upstream, then place them with sonesta.
• The user needs a written report. Use gutenberg and reserve sonesta for executive summary slides.
• The user needs spreadsheet formulas or workbook tabs. Use herndon instead.
• The source analysis is still changing. Keep slide specs linked to stable output paths and rerender after upstream updates.

Decision rule for the calling agent

Before dispatching to sonesta, confirm:

1. The intended artifact is a PowerPoint presentation.
2. The slide structure can be specified as JSON or generated from analysis outputs.
3. Reproducibility and validation matter.
4. Required content fits supported slide elements: text, image, shape, table, chart, notes, templates, or themes.

If yes to the first three, sonesta is the right method.

Inputs and elicitation

Deck objective and audience

What it is: the presentation purpose, audience, length, and desired call to action.

How the agent elicits this:

• Ask who will read the deck and what decision it should support.
• Ask for target slide count and whether the deck is for live presentation or leave-behind.
• Ask whether speaker notes are needed.

Default to suggest: a concise executive deck with title, context, key findings, evidence, recommendation, and appendix slides.

Fallback: if the user only has raw outputs, create a skeleton deck and leave content slots explicit.

Slide content and assets

What it is: slide specs plus images, charts, logos, and tables that need placement.

How the agent elicits this:

• Ask which plots/tables from upstream analysis should become slides.
• Ask whether assets already exist and where they are stored.
• Ask whether charts should be native deck elements or rendered images.
• Ask for any brand/theme constraints.

Default to suggest: place complex charts as generated image assets; use native text/table elements for editable slide content.

Fallback: if assets are missing, create placeholder slides and mark asset paths as TODOs only for draft work.

Layout and template choices

What it is: slide size, theme, templates, layout slots, and element ordering.

How the agent elicits this:

• Ask whether the deck should use an existing template or package theme.
• Ask which content should be prominent on each slide.
• Ask whether explicit coordinates are required or template slots are enough.

Default to suggest: use templates/slots for repeated slide types and explicit placement only for custom analysis slides.

Fallback: when layout is uncertain, render a draft deck and inspect slide summaries before final polish.

Outputs

sonesta produces:

• Project scaffolding with presentation specs, slide specs, assets, themes, and templates.
• Validation and inspection output for presentations, slides, assets, and layout references.
• Rendered .pptx decks or individual slide renders where supported.
• Stable JSON specs that can be regenerated after upstream data changes.

Workflow

Canonical sequence:

1. sonesta init <project> — create a deck project.
2. sonesta themes and sonesta templates — inspect available design resources.
3. sonesta new ... — create presentations, slides, or resources.
4. sonesta slides ... — add, order, and mutate slide elements.
5. sonesta assets ... — inspect or register images and supporting files.
6. sonesta validate <presentation> — catch missing assets, invalid specs, and layout issues.
7. sonesta inspect <presentation> — review deck structure.
8. sonesta render <presentation> — generate the .pptx.
9. sonesta render-slide ... when inspecting or debugging a particular slide.

Worked examples

Building an executive summary deck

User: "Can you turn the analysis into a short deck?"

Agent: "Sonesta is the deck builder. I’ll make a 6-slide structure: title, decision context, key result, evidence chart, risks, recommendation. Do you want a live-presented deck with sparse slides or a leave-behind with more text?"

User: "Leave-behind, but still concise."

Agent: "I’ll use editable text for claims and place the analysis figures as image assets, then validate before rendering."

sonesta init deck_out
sonesta themes
sonesta new presentation decision_review
sonesta new slide decision_review title
sonesta new slide decision_review key_result
sonesta slides add-text decision_review key_result headline --text "Recommended option: B"
sonesta assets inspect writeup/plots/result.png
sonesta validate deck_out/presentations/decision_review.json
sonesta render deck_out/presentations/decision_review.json

Output: a reproducible .pptx generated from JSON specs and assets.

Debugging one slide

sonesta validate presentation.json --format json
sonesta inspect presentation.json --format json
sonesta render-slide presentation.json --slide key_result

Output: validation/inspection data plus a focused render for the problem slide.

Quick command reference

For full options, run sonesta <subcommand> --help.

Command	Purpose
sonesta init	Initialize a deck project.
sonesta themes / templates	Inspect available design resources.
sonesta new ...	Create presentations, slides, or related specs.
sonesta slides ...	Manage slide order and elements.
sonesta assets ...	Inspect project assets.
sonesta validate	Validate presentation and slide specs.
sonesta inspect	Summarize deck structure and references.
sonesta render	Generate a .pptx deck.
sonesta render-slide	Render or inspect a single slide.

Common pitfalls

• Complex charts are usually more reliable as image assets than as reconstructed native chart elements.
• Draft placeholder assets should not survive final validation; missing asset warnings matter.
• Manual PowerPoint edits are not durable unless the JSON specs are updated too.
• Decks for live presentation and leave-behinds need different text density; elicit this early.
• Slide IDs and element IDs should be stable so later mutations target the right object.

Cross-references

• Upstream: dcf, mcda, voting, and labeling can produce results for slides.
• Adjacent outputs: gutenberg for reports; herndon for Excel workbooks.
• QA companion: tufte checks standalone plot images before they are placed into slides.

State contract

A sonesta project contains presentation JSON, slide JSON, assets, themes, templates, and rendered outputs. JSON specs are the source of truth; rendered .pptx files are reproducible artifacts. Agents should validate specs before rendering and avoid treating manual deck edits as durable state.

JSON output and error codes

Commands support structured output where implemented. Treat validation errors as spec problems: inspect the referenced slide, element, asset, or theme path; correct the JSON or CLI-created resource; and rerun sonesta validate.