ppt-agent-pipeline

name

ppt-agent-pipeline

description

Service-oriented AI PowerPoint generation workflow for LAN or web agents. Use when designing, implementing, optimizing, or operating a backend agent that creates or edits editable .pptx decks from chat requirements, source files, templates, or company style rules; when combining pptxgenjs/OOXML editing, embedded vector-to-PowerPoint rendering, and preview/layout QA; or when deciding which PPT generation route to use for a production-like service.

PPT Agent Pipeline

Use this skill to build, optimize, or run a service-ready PPT generation pipeline. The goal is not a single magic renderer; it is a routing layer that combines three strengths:

• pptxgenjs and OOXML editing for stable service generation, templates, native charts, precise edits, low latency, and low token use.
• Embedded spec_lock, SVG quality checks, and vector-to-PowerPoint paths for complex visual pages and editable vector design drafts.
• Presentations-style claim planning, deterministic layout inspection, and fix-and-verify QA for client-ready quality.

Bundled Runtime

This pipeline is bundled with the LoopPPT web app. The web app may call any supported, already logged-in coding-agent CLI, but the job contract and validator live inside this project.

Before relying on local toolchains, run from the app root:

python3 src/server/pipeline/ppt-agent-pipeline/scripts/check_env.py

Do not assume user-specific skill directories or downloaded tool folders exist on another machine. Prefer project-bundled templates, project-bundled validators, standard Node/Python tools, and packages available in the active agent CLI environment.

Production Default

For a LAN chat-to-PPT service, default to:

1. Plan with a compact claim spine and slide_plan.json.
2. Render ordinary slides with pptxgenjs or template OOXML.
3. Route only visual-heavy slides to the embedded vector-to-PowerPoint module.
4. Run source-level layout/placeholder QA while generating the deck; the web app renders final previews and runs structural/layout validation. LibreOffice openability checks are optional and may be enabled by the host app.
5. Return final.pptx. Retain qa_report.md only when the job explicitly enables the internal QA report.

This keeps the fast/cheap renderer as the base while borrowing vector-design quality discipline and Presentations-style visual verification.

When the app runs a separate agent pass, use the matching short pass contract instead of re-reading this full workflow document: references/planning-pass.md, references/generation-pass.md, references/repair-pass.md, or references/revision-pass.md.

Template Package Contract

When request.json.template is present, treat it as the selected PPT-generation template package:

• kind: "deck-derived": a reusable style template distilled from a finished PowerPoint deck. Read templateDir/SKILL.md, references/design_spec.md, and references/spec_lock.md when present. Use references/sample_svgs/ to learn page rhythm and reusable layout patterns, but do not copy the original deck's business content.
• kind: "pptx-imported": a user/company PowerPoint reference imported into the app. Prefer OOXML/template-preserving routes when useful, read references/manifest.json if present, and preserve the source brand grammar while generating a new deck.
• template.pptx, when present, is a style/master reference and may be copied into the job workspace. Never overwrite it. The final deliverable must still be a new editable output/final.pptx.
• references/content/content-background.png, when present, is fixed brand chrome extracted from the template master. Use it only in master reference mode; do not use it in style reference mode. It must never prescribe the title/body/column arrangement or restrict the content layout.
• references/content/content-recipe.json, when present, records the source slide and header geometry. Keep titles fully inside titleBox and body content below headerBoundaryY; never overlap fixed header chrome.
• During the generation pass only, templateExperiencePath / references/template-experience.md is required reading when the app prompt provides it. It is read-only code-level memory from repaired successful jobs; use its Failure mode / Failure cause / Improvement rows as generation-code guardrails only. Do not read it during planning, append to it, rewrite it, copy it into the job workspace, quote it in the deck, or treat it as slide content.
• A slide_plan.json claim is planning metadata, not a mandatory visible subtitle. Do not render every claim below the title or add decorative divider bars to every content slide or every repeated card; use those elements only when the individual page benefits from them.
• When drawing repeated cards or columns in a loop, position every divider and decoration relative to the current item. Never stack identical shapes at one fixed coordinate.
• references/brand/brand-spec.md, when present, is the real-asset source of truth. Use its provided logo, product image, and UI screenshot files ahead of generic decoration or invented brand substitutes.
• Image files supplied with a job may be used as real logos, product imagery, or UI screenshots when the user's request identifies their role. Never invent a brand meaning or claim from an unlabeled upload.

Do not use screenshot-only HTML references as the main template source. HTML previews inside a template folder are for picker preview only.

Generation Policy

The web app has one user-facing generation route: generate a complete editable PPTX directly from the selected template and source material. Do not introduce a pre-generation visual approval pause or user-visible quality preset.

• Use pptxgenjs/OOXML as the editable base route.
• When using pptxgenjs, all x, y, w, and h values are in inches. Use the actual selected layout dimensions (for example LAYOUT_16x9 is 10 x 5.625 inches); never place shapes with raw 1280 x 720 pixel coordinates on an inch-based layout.
• Never pass negative w or h values to PptxGenJS shapes or lines. Normalize the origin and use positive dimensions with flipH and/or flipV to preserve direction; negative OOXML extents cause Microsoft PowerPoint to report damaged content and repair the file.
• fontFace must be one real PowerPoint font name, not a CSS font-family stack. For Chinese decks use a platform-appropriate installed CJK font or an explicit conservative fallback strategy.
• Use embedded vector work only on pages where it materially improves communication or template fidelity.
• The app produces final per-slide previews and structural/layout validation after output/final.pptx is written. Do not spend generation turns probing renderers; LibreOffice openability checks are host-configurable.
• Keep revisions targeted: regenerate an affected slide rather than starting a second full planning cycle.

Route The Job

Choose exactly one primary route per job, then add secondary modules only where they solve a concrete weakness.

Situation	Primary route	Add-on
LAN/web service MVP, company templates, repeatable decks	pptxgenjs or native OOXML generation in the job workspace	Source-level layout QA; app final preview check
Editing an existing .pptx, reusing a template, preserving master/layout grammar	OOXML unpack/edit/clean/pack in the job workspace	Slide-level visual QA
Complex cover, infographic, highly designed visual page, unusual canvas ratio	Embedded vector module	spec_lock + SVG checker + native PPTX export
Board/investor/strategy deck where narrative quality matters most	Presentations workflow as quality bar	Use service renderer only after claim spine and design system are locked
Data chart must remain editable as a chart	pptxgenjs native addChart	Do not turn that chart into a static visual insert
Poster/story/social/A4 output plus PPT handoff	Flexible canvas format	Export PPTX plus SVG/PDF previews

Default for a production-ish LAN service: pptxgenjs or OOXML as the primary renderer, with the embedded vector module only for selected visual slides and Presentations as the QA bar, not the default service runtime.

Service Pipeline

Use this artifact contract for every backend job:

1. Create a job workspace: jobs/<job_id>/.
2. Persist inputs: request.json, uploaded sources, selected template, and chat transcript.
3. Normalize sources into sources.md or structured tables.
4. Produce outline.md: audience, goal, page count, core claims.
5. Produce design_system.json: top-level palette and fonts objects, chart style, icon policy, template choice.
6. Produce slide_plan.json: one record per slide with claim, proof object, layout, renderer route, source refs, and editability requirements.
7. Generate the draft .pptx using the selected primary route.
8. Run source-level QA, fix issues, and regenerate affected slides when needed. Write qa_report.md only when request.json.retainQaReport is true; normal jobs retain validation failures for repair but not a narrative QA report.
9. Return final.pptx and write a concise content-specific filename without the extension to output/download-name.txt; the web app renders previews and runs final validation.

Keep all intermediate files under the job workspace. Never overwrite a user template; copy it into the job workspace first. An editable PPTX with text objects outside its slide bounds, or major text-to-text collisions inside the canvas, is a failed deliverable, even when its ZIP structure and slide count are valid.

For local debugging, the job contract validator is:

python3 src/server/pipeline/ppt-agent-pipeline/scripts/validate_job.py jobs/<job_id>

When --require-final is used, the validator checks output/final.pptx and the download name. PPTX openability/renderability through LibreOffice remains available, but normal LoopPPT runs may skip it with PPT_AGENT_SKIP_RENDER_CHECK=1.

Agent Conversation Rules

For a web chat agent, collect enough detail to avoid arbitrary decks:

• Purpose and audience.
• Desired page count or time limit.
• Source material and required facts.
• Company template or style constraints.
• Whether charts need to remain data-editable.
• Any explicit visual emphasis or delivery deadline.

Ask one compact clarification bundle when these are missing. After that, make conservative choices and proceed.

Cost And Token Controls

• Keep user conversation summarization separate from slide generation. Write requirements once into request.json and reuse structured artifacts.
• Do not ask the model to rewrite a whole deck for a single-slide edit; patch slide_plan.json and regenerate affected slides.
• Prefer deterministic layout components for repeated slide types.
• Reserve vector-heavy rendering for slides whose visual complexity justifies higher token and time cost.
• Cache previews and source normalization outputs by job/version.
• For batches, reuse template layout recipes and structured planning outputs before expanding visual complexity.

Quality Gate

Every generated deck must pass final app-managed structural/layout validation. During agent generation, focus on source-level checks:

1. Check for text overflow, overlaps, low contrast, broken images, wrong page order, leftover placeholders, bad wrapping, and chart label collisions.
2. Fix the source route, not only the generated artifact.
3. Regenerate affected slides.
4. Finish once output/final.pptx and required artifacts are written; the app handles final preview/validation.

P0/P1 defects always block delivery. When an internal QA report is explicitly enabled, record any visible residual P2 issue there; otherwise fix visible P2 issues when feasible before delivery without persisting a report.

For detailed service architecture, routing, and QA guidance, read only the relevant reference:

• references/service-architecture.md
• references/toolchain-router.md
• references/render-qa.md

Implementation Bias

• Prefer native editable objects over screenshots.
• Prefer native charts when users may update data later.
• Prefer company templates for repeatable internal use.
• Prefer deterministic scripts for fragile Office packaging steps.
• Treat vector-rendered pages as high-value visual inserts, not the default for every service job.
• Treat Codex Presentations as the quality model and optional Codex-local workflow, not the first service API to depend on.