Prepares the prompt + JSON schema for the CLIENT to generate a slide outline.

This tool does NOT call an LLM. It normalizes inputs, creates/loads the project, saves the presentation metadata, and returns the system prompt, user prompt, and the JSON schema the outline must conform to. You (the client) then generate the outline JSON that follows response_schema, and pass it to ingest_outline.

IMPORTANT — Required checks before calling: Before calling this tool, you must ask the user to confirm the following items:

1. Presentation purpose (purpose): e.g., "internal tech sharing", "customer proposal", "conference talk"

2. Presentation time (presentation_minutes): how many minutes the presentation will be

3. Audience type (audience_type): general/technical/executive

4. Presenter info (presenter_name, presenter_title, presenter_org): presenter_org can be empty if not applicable. If the user has not explicitly provided these, never use default values — always ask.

Args: topic: Presentation topic (e.g., "2024 Cloud Computing Trends") purpose: Presentation purpose. Must confirm with the user before setting. audience_type: "general" | "technical" | "executive". Must confirm with the user. presentation_minutes: 3~60 min. Must confirm with the user. num_slides: Recommended number of slides (0 = auto-calculate from presentation time). presenter_name: Presenter's name. Must confirm with the user. presenter_title: Presenter's job title. Must confirm with the user. presenter_org: Presenter's organization (can be empty). Must confirm with the user. project_id: Project ID (auto-generated if not specified)

Returns: JSON string with: system_prompt, user_prompt, response_schema, project_id.

Next step: Generate the outline JSON matching response_schema, then call ingest_outline(project_id=<project_id>, outline_json=<your JSON>).

Ingests the client-generated outline JSON: validates, injects presenter info, saves.

Call this AFTER prepare_outline, passing the outline JSON you generated following the returned response_schema.

IMPORTANT: After ingesting, you must show the outline to the user and get confirmation (number of slides, titles, content composition) before proceeding to the next step (prepare_design_slide). If the user requests changes, incorporate them and call ingest_outline again with the revised JSON.

Args: project_id: Project ID returned by prepare_outline (required). outline_json: The outline JSON generated by the client, matching the schema from prepare_outline ({"slides": [...]}).

Returns: JSON string containing outline_path and project_id.

Prepares the prompt for the CLIENT to draft DESIGN.md (design intent).

No LLM call. If DESIGN.md already exists, returns {"skip": true} — reuse the existing design intent (do not regenerate). Otherwise returns system_prompt, user_prompt, and project_id. Generate the draft JSON (theme + tone + page_requests) following the prompt's output_format, then call ingest_design_doc_draft.

Call this ONCE before generating slides, so every slide shares one design theme and narrative arc.

Args: project_id: Project ID. Loads outline from the saved project. outline_json: Full outline JSON. Optional if project_id is given. color_theme: Color theme ("dark" or "light", default: "dark").

Returns: JSON with system_prompt, user_prompt, project_id, color_theme — or {"skip": true}.

Ingests the client-generated DESIGN.md draft and saves DESIGN.md.

Call AFTER prepare_design_doc_draft with the draft JSON you generated.

Args: project_id: Project ID (required). draft_json: Draft JSON (theme + tone + page_requests) from the client. color_theme: Color theme (stored into the theme).

Returns: JSON with project_id and design_doc_path.

Prepares the prompt + JSON schema for the CLIENT to generate ONE slide's design spec.

No LLM call. Returns the system prompt, user prompt (with adjacent-slide context and DESIGN.md directives baked in), the response_schema the spec must match, and a thinking_budget hint. Generate the slide spec JSON that conforms to response_schema, then call ingest_design_slide.

Parallelize across slides: call prepare→generate→ingest for each slide concurrently. Slides are independent server-side. Call prepare_design_doc_draft/ingest_design_doc_draft FIRST so all slides share one theme.

Args: project_id: Project ID (required). slide_index: 1-based slide number to generate. outline_json: Full outline JSON. Optional if project_id has a saved outline. total_slides: Total slide count (0 = infer from outline). color_theme: Color theme ("dark" or "light").

Returns: JSON with system_prompt, user_prompt, response_schema, slide_type, thinking_budget, project_id, slide_index.

Ingests the client-generated slide spec: validate, normalize, save, render, lint.

Call AFTER prepare_design_slide with the spec JSON you generated.

Args: project_id: Project ID (required). slide_index: 1-based slide number (same as prepare). spec_json: The slide spec JSON generated by the client, matching the schema. color_theme: Color theme ("dark" or "light").

Returns: JSON with status, slide_file, slide_html_path, optional lint and overflow.

After ingesting ALL slides, call finalize_design_spec once.

Finalizes a freshly generated deck: builds slides.html, runs deck-wide lint.

No LLM call. Call ONCE after all slides have been ingested via ingest_design_slide. Pass the collected overflow items (if any) as JSON.

Args: project_id: Project ID (required). overflow_json: JSON array of overflow items collected from ingest calls (optional, "" if none).

Returns: JSON with design_spec_dir, slide_count, slides_html_path, lint, overflow.

IMPORTANT — Required follow-up: call export_html(project_id=<project_id>) and share slides_html_path with the user.

Moves a slide from one position to another. No LLM call — pure file reordering.

Reorders all related files (outline, design_spec, slide HTML) atomically. After this call, you must call export_html(project_id=<project_id>) to refresh HTML.

Args: project_id: Target project ID (required) from_index: Current slide position (1-based). to_index: Desired slide position (1-based).

Returns: JSON string containing project_id, slide_count, from_index, to_index.

Deletes a slide. No LLM call — pure file removal + reindex.

Args: project_id: Target project ID (required) slide_index: Slide position to delete (1-based).

Returns: JSON string containing project_id and the new slide_count.

After this call, call export_html(project_id=<project_id>) to refresh HTML.

Prepares to add or update ONE slide — updates the outline, returns a generation task.

No LLM call. For add: shifts files and inserts the new outline. For update: updates the outline (if title/content_summary given). Returns the slide generation prompt + response_schema. Generate the slide spec JSON, then call ingest_slide_edit with the SAME action and slide_index.

For narrow single-element tweaks, use prepare_modify_component instead.

Args: project_id: Target project ID (required). action: "add" | "update". slide_index: 1-based position. add: insertion point (-1 = end). update: target. title: Slide title (required for add; required for update on imported projects). content_summary: Content description (required for add; required for update on imported). component_hint: Layout hint (default: "bullets"). slide_type: "title" | "content" | "closing" | "agenda" (default: "content"). speaker_notes: Optional speaker notes. color_theme: Color theme ("dark" or "light").

Returns: JSON with system_prompt, user_prompt, response_schema, action, project_id.

Ingests an add/update slide spec: validate, save (insert for add), render, lint.

Call AFTER prepare_slide_edit with the same action/slide_index and your spec JSON.

Args: project_id: Target project ID (required). action: "add" | "update" (same as prepare). slide_index: 1-based position (same as prepare; use the insertion point for add). spec_json: The slide spec JSON generated by the client. color_theme: Color theme ("dark" or "light").

Returns: JSON with design_spec_dir, slide_count, slide_index, slide_html_path, optional lint.

IMPORTANT — Required follow-up: call export_html(project_id=<project_id>).

Prepares a narrow single-component edit on a content slide.

No LLM call. Returns a generation task with stage:

• stage="modify": generate the ComponentModify JSON, then call ingest_modify_component.

• stage="backfill" (imported slides with no design_doc): generate the backfill JSON, call ingest_backfill to get available_components, then call prepare_modify_component again with a valid component_id.

Use for narrow changes like "make the LLM box red". For broader changes use prepare_slide_edit(action="update").

Args: project_id: Target project ID (required). slide_index: 1-based slide position. component_id: Target component id from design_doc.layout leaf. instruction: Natural-language description of the change. color_theme: Color theme ("dark" or "light").

Returns: JSON with system_prompt, user_prompt, response_schema, stage, project_id, slide_index, component_id.

Ingests the design_doc backfill for an imported slide (stage="backfill").

Call AFTER a prepare_modify_component that returned stage="backfill". Saves the backfilled design_doc and returns available_components. Pick a component id and call prepare_modify_component again.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. backfill_json: The backfill JSON generated by the client.

Returns: JSON with status="backfilled", available_components.

Ingests a single-component edit: validate, apply to exactly one element, save, render.

Call AFTER a prepare_modify_component that returned stage="modify".

Args: project_id: Target project ID (required). slide_index: 1-based slide position. component_id: Target component id (same as prepare). modify_json: The ComponentModify JSON generated by the client. color_theme: Color theme ("dark" or "light").

Returns: JSON with modified_element, slide_html_path, optional lint.

After this call, share the returned slide_html_path with the user.

Prepares a design-rule review task for ONE slide (mechanical lint baked in as a hint).

No LLM call. Returns the review prompt + response_schema. Generate the review JSON, then call ingest_review. Review slides in parallel.

Args: project_id: Target project ID (required). slide_index: 1-based slide position.

Returns: JSON with system_prompt, user_prompt, response_schema, project_id, slide_index.

Ingests a slide's review result: validate, return issues (report-only).

Call AFTER prepare_review. Does NOT auto-regenerate. If has_high_severity, the response includes fix_feedback — pass it into prepare_slide_edit( action="update") to regenerate the slide with the review feedback applied.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. review_json: The review result JSON generated by the client.

Returns: JSON with has_high_severity, issues, optional fix_feedback.

Exports the design spec as an editable PPTX file.

Operates in two modes:

1. When design_spec_json is provided: Generates PPTX directly from design spec (fast and accurate)

2. When only project_id is provided: Auto-loads design spec from project directory to generate PPTX (recommended)

Args: design_spec_json: Design spec JSON string project_id: Project ID (auto-generated if not specified). When provided alone, auto-loads the design spec

Returns: JSON string containing project_id and pptx_path

Imports an external PPTX file and converts it to a design spec for editing.

Reads the PPTX file, extracts all design elements (shapes, textboxes, images, backgrounds, speaker notes), and creates a new project with the design spec. HTML preview is automatically generated.

After import, you can use prepare_slide_edit / ingest_slide_edit, prepare_modify_component / ingest_modify_component, export_html, export_pptx, and the visual QA tools on the imported project.

Args: file_path: Absolute path to the PPTX file to import project_id: Project ID (auto-generated if not specified)

Returns: JSON string containing project_id, num_slides, slides_html_path, and warnings

Generates per-slide HTML files and an iframe container based on the design spec.

Operates in two modes:

1. When design_spec_json is provided: Deterministically converts design spec to HTML (no LLM, fast and accurate)

2. When only project_id is provided: Auto-loads design spec from project directory for HTML conversion (recommended)

Each slide is generated as slides/slide_NN.html, and slides.html is the iframe container.

Args: design_spec_json: Design spec JSON string project_id: Project ID (auto-generated if not specified). When provided alone, auto-loads the design spec

Returns: JSON string containing session_id, slides_html_path, slide_count, project_id

Retrieves the list of existing projects.

Checks the ~/.ppt-generator/ directory and returns the list of saved projects. Includes each project's ID, topic, slide count, completed steps, source, and creation time. Most recent projects are listed first.

The "source" field indicates how the project was created:

• "generated": Created via the prepare_outline / ingest_outline pipeline (has outline)

• "imported": Created via import_pptx (no outline — edit the design spec directly)

When to use: Always call this tool first before starting the PPT generation pipeline.

• If no projects exist: Start a new project (call prepare_outline).

• If projects exist: Guide the user to choose whether to continue an existing project or start a new one.

• For imported projects: Skip outline step and work directly with design spec.

Returns: Project list JSON string. Empty array [] if no projects exist.

Loads project status and metadata.

Checks the saved project's topic, slide count, and completion status of each step. The "source" field indicates how the project was created:

• "generated": Created via the prepare_outline / ingest_outline pipeline (has outline)

• "imported": Created via import_pptx (no outline available)

For imported projects: Since there is no outline, skip outline modification steps. Use prepare_slide_edit / ingest_slide_edit or prepare_design_slide / ingest_design_slide directly to modify slides.

Args: project_id: Project ID

Returns: Project metadata JSON string including source field

Loads the saved outline JSON.

Retrieves the previously generated slide outline from the project directory. The loaded result can be used directly as input for prepare_design_slide or export_html.

Args: project_id: Project ID include_content: If True, returns full slide outline content alongside path. Defaults to False (path and slide_count only).

Returns: JSON string containing outline_path, slide_count, and optionally slides array

Saves (overwrites) a single slide outline to the project.

Creates or overwrites the outline file for a specific slide index. Use this before calling prepare_slide_edit(action="update") to provide the updated slide content that the LLM will use for design spec generation.

For adding new slides: Use prepare_slide_edit(action="add") directly — it accepts outline parameters (title, content_summary, etc.) and handles all file shifts automatically. No need to call this tool first.

For updating existing slides:

1. Call save_outline_slide to overwrite the outline at slide_index.

2. Call prepare_slide_edit(action="update", slide_index=...) to regenerate the design. (Or pass title/content_summary directly to the slide_edit update.)

Args: project_id: Target project ID (required) slide_index: Target slide position (1-based). E.g., 1 for the first slide. title: Slide title content_summary: Detailed slide content description for the LLM component_hint: Layout hint ("bullets", "step_cards", "comparison_table", "arch_diagram", etc.) slide_type: Slide type ("title", "content", "closing", "agenda") speaker_notes: Optional speaker notes layout_plan: Content layout plan (arrangement direction, elements, relationships)

Returns: JSON string containing project_id, slide_index, outline_path

Loads the saved design spec.

Retrieves the previously generated design spec (PptxSlideSpec JSON) from the project directory. The project_id can be passed to export_html(project_id=...) or export_pptx(project_id=...).

Args: project_id: Project ID

Returns: JSON string containing design_spec_dir, slide_count, slide_files

Captures slide screenshots via Playwright (server-side). No LLM call.

Phase 1 of visual QA. Renders the current slide HTML to PNG so the CLIENT can analyze them for visual defects. Requires: playwright install chromium.

Args: project_id: Target project ID (required). slide_indices: 1-based comma-separated indices (e.g. "1,3,5"). Empty = all. iteration: Iteration counter (0-based) — screenshots are versioned per iteration.

Returns: JSON with project_id, iteration, screenshots: [{slide_index, screenshot_path}].

Next: for each captured slide, call prepare_visual_qa_analysis.

Prepares the vision analysis task for ONE captured slide. No LLM call.

Returns the system prompt, user prompt, response_schema, and images (the screenshot path to read). Read the screenshot, analyze it against the spec, generate the analysis JSON matching response_schema, then call ingest_visual_qa_analysis. Analyze slides in parallel.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. iteration: Iteration counter matching the capture (default 0).

Returns: JSON with system_prompt, user_prompt, response_schema, images, project_id, slide_index.

Ingests the client-generated analysis: validate, report issues. No fix applied.

Call AFTER prepare_visual_qa_analysis. If has_issues, call prepare_visual_qa_fix with the returned issues to generate a fix.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. analysis_json: The analysis JSON generated by the client.

Returns: JSON with has_issues, issues (dicts to feed into the fix step), overall_quality.

Prepares the fix task for a slide with detected issues. No LLM call.

Returns the fix prompt, response_schema, and images (the screenshot). Generate the corrected full slide spec JSON, then call ingest_visual_qa_fix.

Args: project_id: Target project ID (required). slide_index: 1-based slide position. issues_json: JSON array of issues from ingest_visual_qa_analysis. iteration: Iteration counter matching the capture (default 0).

Returns: JSON with system_prompt, user_prompt, response_schema, images, project_id, slide_index.

Ingests the client-generated fix: validate, save, re-render HTML.

Call AFTER prepare_visual_qa_fix. Restores images/slide_type the LLM can't produce. Re-run capture → analysis on this slide to verify (up to max_iterations).

Args: project_id: Target project ID (required). slide_index: 1-based slide position. fix_json: The corrected slide spec JSON generated by the client.

Returns: JSON with status ("fixed" | "unfixed"), slide_html_path.

Rebuilds the deck container HTML + full export after visual QA fixes. No LLM call.

Call ONCE after all fix iterations are done.

Args: project_id: Target project ID (required).

Returns: JSON with project_id, slides_html_path.